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.

🤓 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 for database configuration options passed to Knex.js (opens new window)
• settings for Strapi-specific database settings

connection configuration object

Parameter	Description	Type
client	Database client to create the connection. sqlite or postgres or mysql.	String
connection	Database connection information	Object
debug	Show database exchanges and errors.	Boolean
useNullAsDefault Optional, only for SQLite	Use NULL as a default value	Boolean
pool Optional	Database pooling options	Object

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:

Parameter	Description	Type
host	Database host name. Default value: localhost.	String
port	Database port	Integer
database	Database name.	String
user	Username used to establish the connection	String
password	Password used to establish the connection	String
timezone	Set the default behavior for local time. Default value: utc Timezone options (opens new window)	String
schema	Set the default database schema. Used only for Postgres DB.	String
ssl	For 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 (opens new window) database pooling options and accepts the following parameters:

Parameter	Description	Type	Default
min	Minimum number of database connections to keepalive	Integer	0
max	Maximum number of database connections to keepalive	Integer	10
acquireTimeoutMillis	Time in ms before timing out a database connection attempt	Integer	-
createTimeoutMillis	Time in ms before timing out a create query attempt	Integer	-
destroyTimeoutMillis	Time in ms before timing out a destroy query attempt	Integer	-
idleTimeoutMillis	Time in ms before free database connections are destroyed	Integer	-
reapIntervalMillis	Time in ms to check for idle database connections to destroy	Integer	-
createRetryIntervalMillis	Time in ms to idle before retrying failed create actions	Integer	-
afterCreate	Callback function to execute custom logic when the pool acquires a new connection. See the Knex.js documentation (opens new window) 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:

Parameter	Description	Type	Default
forceMigration	Enable or disable the forced database migration.	Boolean	true

Configuration examples

// path: ./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(),
      },
    },
  },
});

// path: ./config/database.js

module.exports = ({ env }) => ({
  connection: {
    client: 'mysql',
    connection: {
      host: env('DATABASE_HOST', '127.0.0.1'),
      port: env.int('DATABASE_PORT', 3306),
      database: env('DATABASE_NAME', 'strapi'),
      user: env('DATABASE_USERNAME', 'strapi'),
      password: env('DATABASE_PASSWORD', 'strapi'),
      ssl: {
        rejectUnauthorized: env.bool('DATABASE_SSL_SELF', false), // For self-signed certificates
      },
    },
    debug: false,
  },
});

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. It currently supports PostgreSQL, SQLite, MySQL and MariaDB.

The following documentation covers how to install SQLite locally (for development purposes):

SQLite

Installation guide for SQLite database

✋ CAUTION

Installation guides for other databases (MySQL, MariaDB) are being reworked. Contributions (opens new window) are most welcome.