Skip to main content

Database configuration

The ./config/database.js file (or the ./config/database.ts file for TypeScript) is used to define database connections that will be used to store the application content.

warning

Strapi applications are not meant to be connected to a pre-existing database, not created by a Strapi application, nor connected to a Strapi v3 database. The Strapi team will not support such attempts. Attempting to connect to an unsupported database may, and most likely will, result in lost data.

Supported databases

The CLI installation guide details supported database and versions.

Configuration structure

The ./config/database.js (or ./config/database.ts for TypeScript) accepts 2 main configuration objects:

connection configuration object

ParameterDescriptionTypeDefault
clientDatabase client to create the connection. sqlite or postgres or mysql.String-
connectionDatabase connection informationObject-
debugShow database exchanges and errors.Booleanfalse
useNullAsDefault

Optional, only for SQLite
Use NULL as a default valueBooleantrue
pool

Optional
Database pooling optionsObject-
acquireConnectionTimeout

Optional
How long knex will wait before throwing a timeout error when acquiring a connection (in milliseconds)Integer60000

Connection parameters

The connection.connection object found in ./config/database.js (or ./config/database.ts for TypeScript) is used to pass database connection information and accepts the following parameters:

ParameterDescriptionType
connectionStringDatabase connection string. When set, it overrides the other connection.connection properties. To disable use an empty string: ''.String
hostDatabase host name. Default value: localhost.String
portDatabase portInteger
databaseDatabase name.String
userUsername used to establish the connectionString
passwordPassword used to establish the connectionString
timezoneSet the default behavior for local time. Default value: utc Timezone optionsString
schemaSet the default database schema. Used only for Postgres DB.String
sslFor SSL database connection.
Use an object to pass certificate files as strings.
Boolean or Object

Database pooling options

The connection.pool object optionally found in ./config/database.js (or ./config/database.ts for TypeScript) is used to pass Tarn.js database pooling options and accepts the following parameters:

caution

When using Docker, change the pool min value to 0 as Docker will kill any idle connections, making it impossible to keep any open connections to the database (see the Tarn.js pool settings used by Knex.js for more information).

ParameterDescriptionTypeDefault
minMinimum number of database connections to keepaliveInteger2
maxMaximum number of database connections to keepaliveInteger10
acquireTimeoutMillisTime in milliseconds before timing out a database connection attemptInteger60000
createTimeoutMillisTime in milliseconds before timing out a create query attemptInteger30000
destroyTimeoutMillisTime in milliseconds before timing out a destroy query attemptInteger5000
idleTimeoutMillisTime in milliseconds before free database connections are destroyedInteger30000
reapIntervalMillisTime in milliseconds to check for idle database connections to destroyInteger1000
createRetryIntervalMillisTime in milliseconds to idle before retrying failed create actionsInteger200
afterCreateCallback function to execute custom logic when the pool acquires a new connection.

See the Knex.js documentation for more information
Function-

settings configuration object

The settings object found in ./config/database.js (or ./config/database.ts for TypeScript) is used to configure Strapi-specific database settings and accepts the following parameter:

ParameterDescriptionTypeDefault
forceMigrationEnable or disable the forced database migration.Booleantrue

Configuration examples

./config/database.js
module.exports = ({ env }) => ({
connection: {
client: 'postgres',
connection: {
host: env('DATABASE_HOST', '127.0.0.1'),
port: env.int('DATABASE_PORT', 5432),
database: env('DATABASE_NAME', 'strapi'),
user: env('DATABASE_USERNAME', 'strapi'),
password: env('DATABASE_PASSWORD', 'strapi'),
schema: env('DATABASE_SCHEMA', 'public'), // Not required
ssl: {
rejectUnauthorized: env.bool('DATABASE_SSL_SELF', false), // For self-signed certificates
},
},
debug: false,
},
});
caution

Strapi is aware that there is an issue regarding SSL support for the server. In order to fix it, you have to set the ssl:{} object as a boolean in order to disable it. See below for example:

module.exports = ({ env }) => ({
connection: {
client: 'postgres',
connection: {
...
ssl: env('DATABASE_SSL', false)
},
},
});

Please note that if you need client side SSL CA verification you will need to use the ssl:{} object with the fs module to convert your CA certificate to a string. You can see an example below:

const fs = require('fs');
module.exports = ({ env }) => ({
connection: {
client: 'postgres',
connection: {
...
ssl: {
ca: fs.readFileSync(`${__dirname}/path/to/your/ca-certificate.crt`).toString(),
},
},
},
});

Configuration in database

Configuration files are not multi-server friendly. To update configurations in production you can use a data store to get and set settings.

Get settings

  • environment (string): Sets the environment you want to store the data in. By default it's current environment (can be an empty string if your configuration is environment agnostic).
  • type (string): Sets if your configuration is for an api, plugin or core. By default it's core.
  • name (string): You have to set the plugin or api name if type is api or plugin.
  • key (string, required): The name of the key you want to store.
// strapi.store(object).get(object);
// create reusable plugin store variable
const pluginStore = strapi.store({
environment: strapi.config.environment,
type: 'plugin',
name: 'users-permissions',
});
await pluginStore.get({ key: 'grant' });

Set settings

  • value (any, required): The value you want to store.
// strapi.store(object).set(object);
// create reusable plugin store variable
const pluginStore = strapi.store({
environment: strapi.config.environment,
type: 'plugin',
name: 'users-permissions'
});
await pluginStore.set({
key: 'grant',
value: {
...
}
});

Databases installation guides

Strapi gives you the option to choose the most appropriate database for your project. Strapi supports PostgreSQL, SQLite, MySQL and MariaDB.

The following documentation covers how to install databases locally: