Supported databases
NocoBase provides eight database dialects. A dialect is the value of dialect in a connection configuration, which selects the database driver. MariaDB shares the mysql dialect with MySQL.
Open-source database drivers
| Database | Driver package | dialect |
|---|---|---|
| SQLite | @nocobase/db-sqlite | sqlite |
| PostgreSQL | @nocobase/db-postgres | postgres |
| MySQL, MariaDB | @nocobase/db-mysql | mysql |
| Microsoft SQL Server | @nocobase/db-mssql | mssql |
| Oracle Database | @nocobase/db-oracle | oracle |
The default application template uses SQLite, so local development needs no separate database server. For other databases, prepare an accessible server, database and account, then install the corresponding driver.
Commercial database drivers
| Database | Driver package | dialect | Requirements |
|---|---|---|---|
| Dameng | @nocobase/db-dameng | dameng | The driver is experimental; verify it against your target database version before use |
| KingbaseES | @nocobase/db-kingbase | kingbase | PostgreSQL-compatible mode, DB_MODE=pg |
| OceanBase CE | @nocobase/db-oceanbase | oceanbase | MySQL-compatible tenant |
These three drivers are NocoBase Pro commercial packages and require the appropriate license. Obtain the private registry URL, account details and a download-enabled read token (nbr_…) from your license provider. Replace <nocobase-pro-registry-url> below with the supplied URL, then run the command and enter the token as the password when prompted:
pnpm login --registry="<nocobase-pro-registry-url>" --scope=@nocobaseThis command maps the @nocobase scope to the Pro registry in user-level configuration. The registry also proxies public NocoBase packages; other dependencies continue to use their existing registry. Keep the token out of documentation, command-line arguments and Git.
Configure the application database
For complete connection examples for each database, see Create an app with a different database. Use connection details from a local server, a separate server or a cloud database.
Install a driver and initialize configuration
Work in the project directory generated by Create an app. The example below uses PostgreSQL in an application that has no config.yml yet. Prepare an accessible PostgreSQL server, database and account, then run:
pnpm add @nocobase/db-postgres@beta
pnpm nocobase config init --dialect postgres --jsonThe command generates config.yml and application secrets without connecting to the database. Fill in the actual host, port, database name, username, password and required TLS settings before connecting. See Create an app with a different database for examples. For another database, substitute its package name and --dialect value. config init does not install drivers or create database servers or accounts.
Keep config.yml out of Git because it can contain passwords and secrets. You can also use the configuration commands to set connection parameters.
After configuration, check the connection:
pnpm nocobase config checkA successful check reports the database connection in the terminal. Problems are reported with the affected settings and suggested fixes. By default, the check connects to databases other than SQLite. Add --connect to include SQLite, or --no-connect to check configuration without connecting. The command does not run migrations.
If config.yml already exists, edit the required connection settings and preserve the existing secrets. Changing dialect does not migrate existing data to another database.
Connection parameters by database
Connections live under database.connections.<name>. database.default selects the default connection, named main in the default template. Common network connection fields are host, port, database, username and password. Adjust these fields for the selected database:
| Database | Configuration details |
|---|---|
| SQLite | Generated configuration uses database for the file. To use filename or DB_FILENAME, remove database and check for a DB_DATABASE override; otherwise database takes precedence. Relative paths resolve under application storage/ |
| PostgreSQL, KingbaseES | Set schema and ssl as needed |
| MySQL, MariaDB, OceanBase | Use database for the database name and username for the user |
| Microsoft SQL Server | Set encrypt and trustServerCertificate to match the server certificate configuration |
| Oracle | Use serviceName to select the service |
| Dameng | Use schema to select the schema; initialization does not generate a database field |
Environment variables can override connection settings in the file; see the Configuration reference for precedence. To add connections, see Multiple database connections. To connect an existing business database and restrict framework schema changes, see Connect existing databases.
Database versions and feature limitations
The following versions are configured as driver integration test targets. They are not a complete compatibility range or a list of minimum supported versions:
| Database | Integration test target |
|---|---|
| PostgreSQL | 16 |
| MySQL | 8.4 |
| MariaDB | 10.11 |
| Microsoft SQL Server | 2022 |
| Oracle Database | Oracle Free 23 |
Your deployment version must also support the features your application uses:
- MySQL and MariaDB: JSON filters use
JSON_OVERLAPS, requiring MySQL 8.0.17+ or MariaDB 10.9+. The expression syntax used for TEXT defaults requires MySQL 8.0.13+ or MariaDB 10.2.1+. See the MySQL driver notes. - OceanBase: Repository fills TEXT field defaults when creating a record. Direct SQL inserts must supply the field value.
- SQLite: Native modules must match the Node.js version, operating system and CPU architecture.
KingbaseES and OceanBase require the modes listed under Supported databases. Verify application queries, migrations and transactions against the target database.
Runtime and package versions
| Item | Requirement or where to check |
|---|---|
| Node.js | 24 or later |
| pnpm | Use the version specified by packageManager in the application's package.json |
| Application template | Check nocobase.defaultTemplateVersion in package.json |
| Core, database drivers and plugins | Install versions that satisfy each package's dependency ranges and peerDependencies; preserve the lockfile |
NocoBase packages have independent version numbers. A package's major version does not identify the NocoBase product version. To inspect your environment and installed packages:
node --version
pnpm --version
pnpm list @nocobase/app-client @nocobase/app-server @nocobase/app-cli @nocobase/db --depth 0Upgrades and cross-platform deployment
Before upgrading, back up the database, runtime configuration and secrets, and preserve the lockfile. Follow Upgrade NocoBase Core to update the template and dependencies, and verify migrations, queries, transactions and permissions in an isolated environment. Reverting code does not undo database schema changes, so prepare a data recovery plan as well.
When deploying to another operating system or CPU architecture, rebuild for the target platform instead of copying local native dependencies. Install database drivers in the application's production dependencies, and rebuild the deployment package after adding a driver. See the Command-line reference for build options and Choose a deployment method for deployment steps.