For production use cases, it is crucial to set all environment variables marked as "Mandatory" to ensure optimal
performance, security, and functionality of NocoDB.
NocoDB maintains full backward compatibility with legacy environment variable names. If you're using older variable names, they will continue to work. However, we recommend using the new naming convention for clarity and consistency. When multiple names are available, the system checks them in this priority order:
New recommended name (e.g., NC_RATE_LIMIT_DATA_API_DURATION)
Legacy name (e.g., NC_DATA_API_TTL)
Default value
This allows for gradual migration without breaking existing deployments.
The primary database where all NocoDB metadata and data are stored. Example format: pg://host.docker.internal:5432?u=username&p=password&d=database_name.
A local SQLite database will be created in the root folder if NC_DB is not specified.
A path to a knex connection JSON file can be used to specify the database connection, as an alternative to NC_DB.
DATABASE_URL
No
A JDBC URL string can be used for the database connection instead of NC_DB.
DATABASE_URL_FILE
No
A path to a file containing a JDBC URL can be specified for the database connection as an alternative to NC_DB.
NC_CONNECTION_ENCRYPT_KEY
No
The key used to encrypt the credentials of external databases. Warning: Changing this variable may break the application. If you must change it, use the CLI as described in the NocoDB Secret CLI documentation.
Keep connection credentials as plain text in the database if not set.
NC_DB_POOL_MAX
No
Maximum number of connections in the database connection pool. Controls how many concurrent database connections NocoDB can maintain.
This JWT secret is utilized for generating authentication tokens.
A random secret will be generated automatically.
NC_JWT_EXPIRES_IN
No
Specifies the expiration time for JWT tokens.
Defaults to 10h.
NC_GOOGLE_CLIENT_ID
No
Google client ID required to activate Google authentication.
NC_GOOGLE_CLIENT_SECRET
No
Google client secret required to activate Google authentication.
NC_ADMIN_EMAIL
No
Super admin email address. This is useful in case you need to recover your username and password. See update requirements.
An initial prompt for email and password is required when accessing the UI for the first time.
NC_ADMIN_PASSWORD
No
Super admin password. Must be at least 8 characters long, including one uppercase letter, one number, and one special character from $&+,:;=?@#'.^*()%!_-\". This is useful for username and password recovery. See update requirements.
NC_DISABLE_EMAIL_AUTH
No
Disables email and password-based authentication, intended for use when Google authentication variables are configured.
NC_REFRESH_TOKEN_EXP_IN_DAYS
No
Specifies the expiration time for refresh tokens in days. Must be a positive number. (On-premise only)
The name of the AWS S3 bucket used for the S3 storage plugin.
-
NC_S3_REGION
No
The AWS S3 region where the S3 storage plugin bucket is located. Note that NC_S3_ENDPOINT takes precedence if set (the endpoint URL includes the region).
-
NC_S3_ENDPOINT
No
S3 endpoint for S3 storage plugin.
Defaults to s3.<region>.amazonaws.com
-
NC_S3_ACCESS_KEY
No
The AWS access key ID for the S3 storage plugin. Required if no role access in use.
-
NC_S3_ACCESS_SECRET
No
The AWS access secret associated with the S3 storage plugin. Required if no role access in use.
Maximum file size allowed for attachments in bytes.
Defaults to 20971520 (20 MiB).
-
NC_FORM_FIELD_MAX_SIZE
No
Sets the maximum size in bytes for individual form fields during multipart uploads in shared form views. Useful for increasing limit for large text or JSON fields to prevent 'Field value too long' errors when form data is submitted by individuals outside your organization.
Defaults to 10485760 (10 MiB).
NC_NON_ATTACHMENT_FIELD_SIZE
NC_MAX_ATTACHMENTS_ALLOWED
No
Maximum number of attachments allowed per cell.
Defaults to 10.
-
NC_ATTACHMENT_RETENTION_DAYS
No
Number of days to retain attachment on storage after all references deleted. (Set 0 to keep forever)
Defaults to 10.
-
NC_ATTACHMENT_ACCESS_CONTROL_ENABLED
No
Enables access control for attachments via pre-signed URLs. Set to true to activate; all other values are treated as false. ⚠ Note: Enabling this will make existing links inaccessible.
Defaults to false.
NC_SECURE_ATTACHMENTS
NC_ATTACHMENT_EXPIRE_SECONDS
No
Time in seconds after which pre-signed URLs for attachments start to expire. The actual expiration will occur after this time plus an additional 10 minutes. Only applicable if NC_ATTACHMENT_ACCESS_CONTROL_ENABLED is enabled.
Defaults to 7200 (2 hours).
-
NC_THUMBNAIL_MAX_SIZE
No
Maximum size in bytes for image files that will generate thumbnails. Images larger than this size will not have thumbnails generated.
Defaults to 3145728 (3 MiB).
-
NC_DATA_IMPORT_FILE_SIZE
No
Maximum file size in bytes accepted by the data import upload endpoint (used when importing CSV / Excel / JSON files into a base).
The following SMTP variables are used to send email notifications to users, e.g., invites.
Variable
Mandatory
Description
If Not Set
NC_SMTP_FROM
Yes
The email address used as the sender for the SMTP plugin.
NC_SMTP_HOST
Yes
The hostname of the email server for the SMTP plugin.
NC_SMTP_PORT
Yes
The network port of the email server for the SMTP plugin.
NC_SMTP_USERNAME
Yes
The username for authentication with the SMTP plugin.
NC_SMTP_PASSWORD
Yes
The password for authentication with the SMTP plugin.
NC_SMTP_SECURE
No
Enables secure authentication for the SMTP plugin. Set to true to enable; all other values are considered false.
Defaults to false.
NC_SMTP_IGNORE_TLS
No
Ignores TLS for the SMTP plugin (disables STARTTLS even if SMTP servers support it). Set to true to ignore; all other values are considered false. Enabling this may compromise security. For more details, see Nodemailer's SMTP documentation.
Defaults to false.
NC_SMTP_REJECT_UNAUTHORIZED
No
Rejects connections to SMTP servers with invalid (self-signed) TLS certificates. Set to true to reject; all other values are considered false. Enabling this hardens security against man-in-the-middle attacks. For more details, see Nodemailer's SMTP documentation.
This is the base URL used for constructing URLs in email templates, generating the Swagger documentation URL, and handling backend URL requirements. It should be set to your public-facing NocoDB URL to ensure consistency across the application.
By default, it infers the URL from the incoming request on the backend. If the server is behind a proxy, this may result in incorrect URLs.
Specifies the Redis URL used for caching. Eg: redis://:authpassword@127.0.0.1:6380/4
Caching layer of backend
NC_REDIS_URL
NC_JOBS_REDIS_URL
No
Separate Redis URL for job queue. Falls back to NC_REDIS_JOB_URL. Useful for isolating job queue workload from cache operations. (On-premise only)
Required if using job queue features.
NC_REDIS_JOB_URL
NC_RATE_LIMIT_REDIS_URL
No
Separate Redis URL for rate limiting. Falls back to NC_THROTTLER_REDIS. Useful for isolating rate limiting operations from cache and jobs. (On-premise only)
(On-premise only) NocoDB implements rate limiting for different API types to prevent abuse and ensure fair usage. Each API type has three configurable parameters: DURATION (time window in milliseconds), MAX_REQUESTS (max requests in that window), and BLOCK_DURATION (how long to block in milliseconds after exceeding limits).
Disables the ability to create bases on external databases.
-
NC_INVITE_ONLY_SIGNUP
No
Disables public signup; signup is possible only via invitations. Integrated into the super admin settings menu as of version 0.99.0.
-
NC_REQUEST_BODY_SIZE
No
Maximum bytes allowed in the request body, based on ExpressJS limits.
Defaults to 1048576 (1 MB).
-
NC_WEBHOOK_ALLOW_PRIVATE_NETWORK
No
Allows webhooks to call private network addresses (localhost, RFC1918 ranges). Set to true to enable; all other values are considered false. ⚠ Security risk.
Defaults to false.
NC_ALLOW_LOCAL_HOOKS
NC_ALLOW_LOCAL_EXTERNAL_DBS
No
Allows connections to external databases on local network addresses, posing potential security risks. Set to true to enable; all other values are considered false.
Defaults to false.
-
NC_DATABASE_COLUMN_NAME_SANITIZE_ENABLED
No
Enables sanitization of column names during creation to prevent SQL injection. Set to false to disable sanitization.
Defaults to true (enabled).
NC_SANITIZE_COLUMN_NAME
NC_APP_DATA_DIR
No
Specifies the directory to store metadata and app-related files. In Docker setups, this maps to /usr/app/data/ for mounting volumes.
Configures logging levels for webhook execution. Possible values: OFF, ERROR, ALL. More details can be found under Webhooks.
Defaults to OFF.
NC_AUTOMATION_LOG_LEVEL
NC_IFRAME_ALLOWED_DOMAINS
No
Comma-separated list of domains allowed to be embedded in iframes. (On-premise only) Example: *.nocodb.com,*.mycompany.com
NC_IFRAME_WHITELIST_DOMAINS
NC_API_BULK_OPERATION_MAX_RECORDS
No
Maximum number of records that can be inserted/updated/deleted in a single v3 API request. Helps prevent memory issues with large bulk operations. (On-premise only)
Defaults to 10 for v3 APIs.
NC_DATA_PAYLOAD_LIMIT
NC_WORKER_MODE_ENABLED
No
Set to true to designate this instance as a background job processor. When enabled, this instance will only process jobs and not serve HTTP requests. (On-premise only)
NocoDB UI is exactly what's in your Postgres database schema. Same tables, same columns—everything is perfectly
mirrored. This is done by creating a schema for each base in PostgreSQL. This feature is enabled by default if the user
has the required permissions. To disable it, set the NC_DISABLE_PG_DATA_REFLECTION environment variable to true.
E2B provides sandboxed cloud environments for executing scripts. These variables are required to enable the Webhook Run Script and Workflow Run Script node features.
Variable
Mandatory
Description
If Not Set
E2B_API_KEY
No
API key for authenticating with the E2B service. Required to enable script execution features.
Script execution features are disabled.
E2B_TEMPLATE_ID
No
The E2B sandbox template ID that defines the execution environment for scripts. Set to yah8ggzfy44fpdop51ai.
Allows to enable various levels of debug logging. Set to nc:* to enable all NocoDB debug logging. Set to nc:*,knex:* to additionally enable database query logging. Recommended only during debugging.
Unset by default.
NC_ENABLE_ALL_API_ERROR_LOGGING
No
Enables more verbose API error logging. Recommended only during debugging.
Defaults to false.
NC_DISABLE_CACHE
No
Disables caching to force metadata fetching directly from the database instead of Redis/cache. Recommended only during debugging.
Disables the telemetry to prevent sending anonymous usage data. Please keep it enabled to help us understand the usage of the product and the impact that any new breaking change can cause.
Litestream is used only when NC_DB is set to SQLite. It backs up the SQLite database and stores it in S3.
Variable
Mandatory
Description
If Not Set
LITESTREAM_S3_ENDPOINT
No
URL of an S3-compatible object storage service endpoint for Litestream replication of NocoDB's default SQLite database. Example: s3.eu-central-1.amazonaws.com.
AWS region of the Litestream replication object storage bucket. Note that LITESTREAM_S3_ENDPOINT takes precedence if configured (the endpoint URL includes the region).
Name of the object storage bucket to store the Litestream replication in.
Litestream replication is disabled if this variable is not set.
LITESTREAM_S3_PATH
No
Directory path to use within the Litestream replication object storage bucket.
Defaults to nocodb.
LITESTREAM_S3_ACCESS_KEY_ID
No
Authentication key ID for the Litestream replication object storage bucket.
Litestream replication is disabled if this variable is not set.
LITESTREAM_S3_SECRET_ACCESS_KEY
No
Authentication secret for the Litestream replication object storage bucket.
Litestream replication is disabled if this variable is not set.
LITESTREAM_S3_SKIP_VERIFY
No
Whether to disable TLS verification for the Litestream replication object storage service. Useful when testing against a local node such as MinIO and you are using self-signed certificates.
Defaults to false.
LITESTREAM_RETENTION
No
Amount of time Litestream snapshot and WAL files are kept. After the retention period, a new snapshot is created and the old one is removed. WAL files that exist before the oldest snapshot will also be removed.
Defaults to 1440h (60 days).
LITESTREAM_RETENTION_CHECK_INTERVAL
No
Frequency in which Litestream will check if retention needs to be enforced.
Defaults to 72h (3 days).
LITESTREAM_SNAPSHOT_INTERVAL
No
Frequency in which new Litestream snapshots are created. A higher frequency reduces the time to restore since newer snapshots will have fewer WAL frames to apply. Retention still applies to these snapshots.
Defaults to 24h (1 day).
LITESTREAM_SYNC_INTERVAL
No
Frequency in which frames are pushed to the Litestream replica. Increasing this frequency can increase object storage costs significantly.
Defaults to 60s (1 minute).
LITESTREAM_AGE_PUBLIC_KEY
No
age public key generated by age-keygen (age1...) or SSH public key (ssh-ed25519 AAAA..., ssh-rsa AAAA...) used to encrypt the Litestream replication for. Refer to the relevant Litestream documentation for details.
Litestream replication is unencrypted if this variable is not set.
LITESTREAM_AGE_SECRET_KEY
No
age secret key (AGE-SECRET-KEY-1...) used to encrypt the Litestream replication with. Refer to the relevant Litestream documentation for details.
Litestream replication is unencrypted if this variable is not set.
AWS_ACCESS_KEY_ID
No
Deprecated. Please use LITESTREAM_S3_ACCESS_KEY_ID instead.
AWS_SECRET_ACCESS_KEY
No
Deprecated. Please use LITESTREAM_S3_SECRET_ACCESS_KEY instead.
AWS_BUCKET
No
Deprecated. Please use LITESTREAM_S3_BUCKET instead.
AWS_BUCKET_PATH
No
Deprecated. Please use LITESTREAM_S3_PATH instead.