import SupportedDatabases from '/docs/snippets/supported-databases.md'

Database configuration#

`/config/database` defines connections, clients, and pooling for supported databases like SQLite, MySQL, and PostgreSQL.

The /config/database.js|ts file is used to define database connections that will be used to store the application content.

:::strapi Supported databases
The following databases are supported by Strapi:

:::

Configuration structure#

The /config/database.js|ts file accepts 2 main configuration objects:

connection for database configuration options passed to
settings for Strapi-specific database settings

`connection` configuration object#

Parameter	Description	Type	Default
`client`	Database client to create the connection. Accepts the following values: `sqlite` for SQLite databases `postgres` for PostgreSQL databases `mysql` for MySQL databases	`String`	-
`connection`	Database connection information	`Object`	-
`debug`	Show database exchanges and errors.	`Boolean`	`false`
`useNullAsDefault` Optional, only for SQLite	Use `NULL` as a default value	`Boolean`	`true`
`pool` Optional	Database pooling options	`Object`	-
`acquireConnectionTimeout` Optional	How long knex will wait before throwing a timeout error when acquiring a connection (in milliseconds)	`Integer`	`60000`

Info

Strapi only supports the following client values, and will automatically rewrite the client value to the following options before passing the configuration to Knex:

`client` value	Actual package used
sqlite
mysql
postgres

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
`connectionString`	Database connection string. When set, it overrides the other `connection.connection` properties. To disable use an empty string: `''`. Available in `v4.6.2`+	`String`
`host`	Database host name. Default value: `localhost`.	`String`
`port`	Database port	`Integer`
`database` or `filename`	Database name or filename. For MySQL or PostgreSQL, use the `database` key (with `host`, `port`, etc.). For SQLite, only provide `filename`` which points to the database file.	`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`	`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 database pooling options and accepts the following parameters:

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 settings used by Knex.js for more information).

Parameter	Description	Type	Default
`min`	Minimum number of database connections to keepalive	`Integer`	`2`
`max`	Maximum number of database connections to keepalive	`Integer`	`10`
`acquireTimeoutMillis`	Time in milliseconds before timing out a database connection attempt	`Integer`	`60000`
`createTimeoutMillis`	Time in milliseconds before timing out a create query attempt	`Integer`	`30000`
`destroyTimeoutMillis`	Time in milliseconds before timing out a destroy query attempt	`Integer`	`5000`
`idleTimeoutMillis`	Time in milliseconds before free database connections are destroyed	`Integer`	`30000`
`reapIntervalMillis`	Time in milliseconds to check for idle database connections to destroy	`Integer`	`1000`
`createRetryIntervalMillis`	Time in milliseconds to idle before retrying failed create actions	`Integer`	`200`
`afterCreate`	Callback function to execute custom logic when the pool acquires a new connection. See the 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 parameters:

Parameter	Description	Type	Default
`forceMigration`	Enable or disable the forced database migration.	`Boolean`	`true`
`runMigrations`	Enable or disable database migrations from running on start up.	`Boolean`	`true`

Configuration examples#

module.exports = ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      connectionString: env('DATABASE_URL'),
      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: env.bool('DATABASE_SSL', false) && {
        rejectUnauthorized: env.bool('DATABASE_SSL_SELF', false), // For self-signed certificates
      },
    },
    pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    debug: false,
  },
});

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(),
      },
    },
  },
});

Example: PostgreSQL with AWS RDS IAM authentication (dynamic password token)

Knex supports short-lived credentials by letting you provide connection.connection as a function and by checking whether a token needs renewal via expirationChecker.

import { Signer } from '@aws-sdk/rds-signer';

export default ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', 'localhost'),
    port: env.int('DATABASE_PORT', 5432),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'postgres',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          host: env('DATABASE_HOST', 'localhost'),
          port: env.int('DATABASE_PORT', 5432),
          database: env('DATABASE_NAME', 'strapi'),
          user: env('DATABASE_USERNAME', 'strapi'),
          password: token,
          schema: env('DATABASE_SCHEMA', 'public'),
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

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,
  },
});

module.exports = ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: env('DATABASE_FILENAME', '.tmp/data.db'),
    },
    useNullAsDefault: true,
    debug: false,
  },
});

import path from 'path';
export default ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(
        __dirname,
        '..',
        '..',
        env('DATABASE_FILENAME', path.join('.tmp', 'data.db'))
      ),
    },
    useNullAsDefault: true,
  },
});

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: {
    ...
  }
});

Dynamic database credentials#

Some cloud providers issue short-lived database credentials that expire after a fixed period. For example, AWS RDS IAM tokens are valid for 15 minutes; GCP Cloud SQL IAM tokens expire similarly; HashiCorp Vault can rotate secrets on a schedule. Using a static password in .env causes intermittent connection failures when the connection pool recycles idle connections after the token has expired.

Strapi supports dynamic credentials through Knex's connection function pattern. Instead of a plain connection object, you can pass a synchronous or asynchronous function to connection.connection. Knex calls this function whenever it needs to open a new database connection, ensuring the pool always receives fresh credentials. This pattern works for PostgreSQL and MySQL/MariaDB. TypeScript types officially accept sync and async functions for connection.connection as of Strapi v5.51.0.

MySQL/MariaDB with AWS RDS IAM authentication#

The following example mints a fresh IAM auth token from the AWS SDK each time the pool opens a new MySQL connection. For a PostgreSQL equivalent, see the PostgreSQL + AWS RDS IAM authentication example in the configuration examples above.

const { Signer } = require('@aws-sdk/rds-signer');

module.exports = ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', '127.0.0.1'),
    port: env.int('DATABASE_PORT', 3306),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'mysql',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          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: token,
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

import { Signer } from '@aws-sdk/rds-signer';

export default ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', '127.0.0.1'),
    port: env.int('DATABASE_PORT', 3306),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'mysql',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          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: token,
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

Environment variables in database configurations#

Strapi version v4.6.2 and higher includes the database configuration options in the ./config/database.js or ./config/database.ts file. When a new project is created the environment variable DATABASE_CLIENT with the value mysql, postgres, or sqlite is automatically added to the .env file depending on which database you choose during project creation. Additionally, all of the environment variables necessary to connect to your local development database are also added to the .env file. The following is an example of the generated configuration file:

const path = require('path');

module.exports = ({ env }) => {
  const client = env('DATABASE_CLIENT', 'sqlite');

  const connections = {
    mysql: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    postgres: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
        schema: env('DATABASE_SCHEMA', 'public'),
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    sqlite: {
      connection: {
        filename: path.join(
          __dirname,
          '..',
          env('DATABASE_FILENAME', 'data.db')
        ),
      },
      useNullAsDefault: true,
    },
  };

  return {
    connection: {
      client,
      ...connections[client],
      acquireConnectionTimeout: env.int('DATABASE_CONNECTION_TIMEOUT', 60000),
    },
  };
};

import path from 'path';

export default = ({ env }) => {
  const client = env('DATABASE_CLIENT', 'sqlite');

  const connections = {
    mysql: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    postgres: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
        schema: env('DATABASE_SCHEMA', 'public'),
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    sqlite: {
      connection: {
        filename: path.join(
          __dirname,
          '..',
          env('DATABASE_FILENAME', 'data.db')
        ),
      },
      useNullAsDefault: true,
    },
  };

  return {
    connection: {
      client,
      ...connections[client],
      acquireConnectionTimeout: env.int('DATABASE_CONNECTION_TIMEOUT', 60000),
    },
  };
};

The following are examples of the corresponding .env file database-related keys for each of the possible databases:


# Database
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strap1
DATABASE_SSL=false


# Database
DATABASE_CLIENT=postgres
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strapi
DATABASE_SSL=false


# Database
DATABASE_CLIENT=sqlite
DATABASE_FILENAME=.tmp/data.db

Environment variables for Strapi applications before `v4.6.2`#

If you started your project with a version prior to v4.6.2 you can convert your database.js|database.ts configuration file following this procedure:

Update your application to v4.6.2 or a later version. See the upgrades documentation.
Replace the contents of your ./config/database.js or ./config/database.ts file with the preceding JavaScript or TypeScript code.
Add the environment variables from the preceding code example to your .env file.
(optional) Add additional environment variables such as DATABASE_URL and the properties of the ssl object.
Save the changes and restart your application.

Do not overwrite the environment variables: HOST, PORT, APP_KEYS, API_TOKEN_SALT, and ADMIN_JWT_SECRET.

Database connections using `connectionString`#

Many managed database solutions use the property connectionString to connect a database to an application. Strapi v4.6.2 and later versions include the connectionString property. The connectionString is a concatenation of all the database properties in the connection.connection object. The connectionString:

overrides the other connection.connection properties such as host and port,
can be disabled by setting the property to an empty string: ''.

Database management by environment#

Development of a Strapi application commonly includes customization in the local development environment with a local development database, such as SQLite. When the application is ready for another environment such as production or staging the application is deployed with a different database instance, usually MySQL, MariaDB, or PostgreSQL. Database environment variables allow you to switch the attached database. To switch the database connection:

set a minimum of the DATABASE_CLIENT and DATABASE_URL for MySQL, MariaDB, and PostgreSQL,
or set a minimum of DATABASE_CLIENT and DATABASE_FILENAME for SQLite.

For deployed versions of your application the database environment variables should be stored wherever your other secrets are stored. The following table gives examples of where the database environment variables should be stored:

Hosting option	environment variable storage
Virtual private server/virtual machine (e.g. AWS EC2)	`ecosystem.config.js` or `.env`
DigitalOcean App Platform	`Environment Variables` table
Heroku	`Config vars` table

Databases installation#

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

SQLite#

SQLite is the default (see Quick Start Guide) and recommended database to quickly create an application locally.

Install SQLite during application creation#

Use one of the following commands:

yarn create strapi-app my-project --quickstart

npx create-strapi-app@latest my-project --quickstart

This will create a new project and launch it in the browser.

Install SQLite manually#

In a terminal, run the following command:

yarn add better-sqlite3

npm install better-sqlite3

Add the following code to your /config/database.ts|js file:

module.exports = ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(__dirname, '..', env('DATABASE_FILENAME', '.tmp/data.db')),
    },
    useNullAsDefault: true,
  },
});

import path from 'path';

export default ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(__dirname, '..', '..', env('DATABASE_FILENAME', '.tmp/data.db')),
    },
    useNullAsDefault: true,
  },
});

PostgreSQL#

When connecting Strapi to a PostgreSQL database, the database user requires SCHEMA permissions. While the database admin has this permission by default, a new database user explicitly created for the Strapi application will not. This would result in a 500 error when trying to load the admin console.

To create a new PostgreSQL user with the SCHEMA permission, use the following steps:

# Create a new database user with a secure password
$ CREATE USER my_strapi_db_user WITH PASSWORD 'password';
# Connect to the database as the PostgreSQL admin
$ \c my_strapi_db_name admin_user
# Grant schema privileges to the user
$ GRANT ALL ON SCHEMA public TO my_strapi_db_user;

import SupportedDatabases from '/docs/snippets/supported-databases.md'

Database configuration#

`/config/database` defines connections, clients, and pooling for supported databases like SQLite, MySQL, and PostgreSQL.

The /config/database.js|ts file is used to define database connections that will be used to store the application content.

:::strapi Supported databases
The following databases are supported by Strapi:

:::

Configuration structure#

The /config/database.js|ts file accepts 2 main configuration objects:

connection for database configuration options passed to
settings for Strapi-specific database settings

`connection` configuration object#

Parameter	Description	Type	Default
`client`	Database client to create the connection. Accepts the following values: `sqlite` for SQLite databases `postgres` for PostgreSQL databases `mysql` for MySQL databases	`String`	-
`connection`	Database connection information	`Object`	-
`debug`	Show database exchanges and errors.	`Boolean`	`false`
`useNullAsDefault` Optional, only for SQLite	Use `NULL` as a default value	`Boolean`	`true`
`pool` Optional	Database pooling options	`Object`	-
`acquireConnectionTimeout` Optional	How long knex will wait before throwing a timeout error when acquiring a connection (in milliseconds)	`Integer`	`60000`

Info

Strapi only supports the following client values, and will automatically rewrite the client value to the following options before passing the configuration to Knex:

`client` value	Actual package used
sqlite
mysql
postgres

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
`connectionString`	Database connection string. When set, it overrides the other `connection.connection` properties. To disable use an empty string: `''`. Available in `v4.6.2`+	`String`
`host`	Database host name. Default value: `localhost`.	`String`
`port`	Database port	`Integer`
`database` or `filename`	Database name or filename. For MySQL or PostgreSQL, use the `database` key (with `host`, `port`, etc.). For SQLite, only provide `filename`` which points to the database file.	`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`	`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 database pooling options and accepts the following parameters:

Parameter	Description	Type	Default
`min`	Minimum number of database connections to keepalive	`Integer`	`2`
`max`	Maximum number of database connections to keepalive	`Integer`	`10`
`acquireTimeoutMillis`	Time in milliseconds before timing out a database connection attempt	`Integer`	`60000`
`createTimeoutMillis`	Time in milliseconds before timing out a create query attempt	`Integer`	`30000`
`destroyTimeoutMillis`	Time in milliseconds before timing out a destroy query attempt	`Integer`	`5000`
`idleTimeoutMillis`	Time in milliseconds before free database connections are destroyed	`Integer`	`30000`
`reapIntervalMillis`	Time in milliseconds to check for idle database connections to destroy	`Integer`	`1000`
`createRetryIntervalMillis`	Time in milliseconds to idle before retrying failed create actions	`Integer`	`200`
`afterCreate`	Callback function to execute custom logic when the pool acquires a new connection. See the 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 parameters:

Parameter	Description	Type	Default
`forceMigration`	Enable or disable the forced database migration.	`Boolean`	`true`
`runMigrations`	Enable or disable database migrations from running on start up.	`Boolean`	`true`

Configuration examples#

module.exports = ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      connectionString: env('DATABASE_URL'),
      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: env.bool('DATABASE_SSL', false) && {
        rejectUnauthorized: env.bool('DATABASE_SSL_SELF', false), // For self-signed certificates
      },
    },
    pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    debug: false,
  },
});

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(),
      },
    },
  },
});

Example: PostgreSQL with AWS RDS IAM authentication (dynamic password token)

Knex supports short-lived credentials by letting you provide connection.connection as a function and by checking whether a token needs renewal via expirationChecker.

import { Signer } from '@aws-sdk/rds-signer';

export default ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', 'localhost'),
    port: env.int('DATABASE_PORT', 5432),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'postgres',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          host: env('DATABASE_HOST', 'localhost'),
          port: env.int('DATABASE_PORT', 5432),
          database: env('DATABASE_NAME', 'strapi'),
          user: env('DATABASE_USERNAME', 'strapi'),
          password: token,
          schema: env('DATABASE_SCHEMA', 'public'),
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

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,
  },
});

module.exports = ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: env('DATABASE_FILENAME', '.tmp/data.db'),
    },
    useNullAsDefault: true,
    debug: false,
  },
});

import path from 'path';
export default ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(
        __dirname,
        '..',
        '..',
        env('DATABASE_FILENAME', path.join('.tmp', 'data.db'))
      ),
    },
    useNullAsDefault: true,
  },
});

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: {
    ...
  }
});

Dynamic database credentials#

MySQL/MariaDB with AWS RDS IAM authentication#

const { Signer } = require('@aws-sdk/rds-signer');

module.exports = ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', '127.0.0.1'),
    port: env.int('DATABASE_PORT', 3306),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'mysql',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          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: token,
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

import { Signer } from '@aws-sdk/rds-signer';

export default ({ env }) => {
  const signer = new Signer({
    hostname: env('DATABASE_HOST', '127.0.0.1'),
    port: env.int('DATABASE_PORT', 3306),
    username: env('DATABASE_USERNAME', 'strapi'),
  });

  return {
    connection: {
      client: 'mysql',
      connection: async () => {
        const token = await signer.getAuthToken();
        const expiresAt = Date.now() + 15 * 60 * 1000;

        return {
          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: token,
          ssl: true,
          expirationChecker: () => expiresAt - Date.now() <= 5 * 60 * 1000,
        };
      },
    },
  };
};

Environment variables in database configurations#

const path = require('path');

module.exports = ({ env }) => {
  const client = env('DATABASE_CLIENT', 'sqlite');

  const connections = {
    mysql: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    postgres: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
        schema: env('DATABASE_SCHEMA', 'public'),
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    sqlite: {
      connection: {
        filename: path.join(
          __dirname,
          '..',
          env('DATABASE_FILENAME', 'data.db')
        ),
      },
      useNullAsDefault: true,
    },
  };

  return {
    connection: {
      client,
      ...connections[client],
      acquireConnectionTimeout: env.int('DATABASE_CONNECTION_TIMEOUT', 60000),
    },
  };
};

import path from 'path';

export default = ({ env }) => {
  const client = env('DATABASE_CLIENT', 'sqlite');

  const connections = {
    mysql: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    postgres: {
      connection: {
        connectionString: env('DATABASE_URL'),
        host: env('DATABASE_HOST', 'localhost'),
        port: env.int('DATABASE_PORT', 3306),
        database: env('DATABASE_NAME', 'strapi'),
        user: env('DATABASE_USERNAME', 'strapi'),
        password: env('DATABASE_PASSWORD', 'strapi'),
        ssl: env.bool('DATABASE_SSL', false) && {
          key: env('DATABASE_SSL_KEY', undefined),
          cert: env('DATABASE_SSL_CERT', undefined),
          ca: env('DATABASE_SSL_CA', undefined),
          capath: env('DATABASE_SSL_CAPATH', undefined),
          cipher: env('DATABASE_SSL_CIPHER', undefined),
          rejectUnauthorized: env.bool(
            'DATABASE_SSL_REJECT_UNAUTHORIZED',
            true
          ),
        },
        schema: env('DATABASE_SCHEMA', 'public'),
      },
      pool: { min: env.int('DATABASE_POOL_MIN', 2), max: env.int('DATABASE_POOL_MAX', 10) },
    },
    sqlite: {
      connection: {
        filename: path.join(
          __dirname,
          '..',
          env('DATABASE_FILENAME', 'data.db')
        ),
      },
      useNullAsDefault: true,
    },
  };

  return {
    connection: {
      client,
      ...connections[client],
      acquireConnectionTimeout: env.int('DATABASE_CONNECTION_TIMEOUT', 60000),
    },
  };
};

The following are examples of the corresponding .env file database-related keys for each of the possible databases:


# Database
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strap1
DATABASE_SSL=false


# Database
DATABASE_CLIENT=postgres
DATABASE_HOST=127.0.0.1
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strapi
DATABASE_SSL=false


# Database
DATABASE_CLIENT=sqlite
DATABASE_FILENAME=.tmp/data.db

Environment variables for Strapi applications before `v4.6.2`#

If you started your project with a version prior to v4.6.2 you can convert your database.js|database.ts configuration file following this procedure:

Update your application to v4.6.2 or a later version. See the upgrades documentation.
Replace the contents of your ./config/database.js or ./config/database.ts file with the preceding JavaScript or TypeScript code.
Add the environment variables from the preceding code example to your .env file.
(optional) Add additional environment variables such as DATABASE_URL and the properties of the ssl object.
Save the changes and restart your application.

Do not overwrite the environment variables: HOST, PORT, APP_KEYS, API_TOKEN_SALT, and ADMIN_JWT_SECRET.

Database connections using `connectionString`#

overrides the other connection.connection properties such as host and port,
can be disabled by setting the property to an empty string: ''.

Database management by environment#

set a minimum of the DATABASE_CLIENT and DATABASE_URL for MySQL, MariaDB, and PostgreSQL,
or set a minimum of DATABASE_CLIENT and DATABASE_FILENAME for SQLite.

Hosting option	environment variable storage
Virtual private server/virtual machine (e.g. AWS EC2)	`ecosystem.config.js` or `.env`
DigitalOcean App Platform	`Environment Variables` table
Heroku	`Config vars` table

Databases installation#

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

SQLite#

SQLite is the default (see Quick Start Guide) and recommended database to quickly create an application locally.

Install SQLite during application creation#

Use one of the following commands:

yarn create strapi-app my-project --quickstart

npx create-strapi-app@latest my-project --quickstart

This will create a new project and launch it in the browser.

Install SQLite manually#

In a terminal, run the following command:

yarn add better-sqlite3

npm install better-sqlite3

Add the following code to your /config/database.ts|js file:

module.exports = ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(__dirname, '..', env('DATABASE_FILENAME', '.tmp/data.db')),
    },
    useNullAsDefault: true,
  },
});

import path from 'path';

export default ({ env }) => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: path.join(__dirname, '..', '..', env('DATABASE_FILENAME', '.tmp/data.db')),
    },
    useNullAsDefault: true,
  },
});

PostgreSQL#

To create a new PostgreSQL user with the SCHEMA permission, use the following steps:

# Create a new database user with a secure password
$ CREATE USER my_strapi_db_user WITH PASSWORD 'password';
# Connect to the database as the PostgreSQL admin
$ \c my_strapi_db_name admin_user
# Grant schema privileges to the user
$ GRANT ALL ON SCHEMA public TO my_strapi_db_user;

Database configuration#

Configuration structure#

connection configuration object#

Connection parameters#

Database pooling options#

settings configuration object#

Configuration examples#

Configuration in database#

Get settings#

Set settings#

Dynamic database credentials#

MySQL/MariaDB with AWS RDS IAM authentication#

Environment variables in database configurations#

Environment variables for Strapi applications before v4.6.2#

Database connections using connectionString#

Database management by environment#

Databases installation#

SQLite#

Install SQLite during application creation#

Install SQLite manually#

PostgreSQL#

Database configuration#

Configuration structure#

connection configuration object#

Connection parameters#

Database pooling options#

settings configuration object#

Configuration examples#

Configuration in database#

Get settings#

Set settings#

Dynamic database credentials#

MySQL/MariaDB with AWS RDS IAM authentication#

Environment variables in database configurations#

Environment variables for Strapi applications before v4.6.2#

Database connections using connectionString#

Database management by environment#

Databases installation#

SQLite#

Install SQLite during application creation#

Install SQLite manually#

PostgreSQL#

`connection` configuration object#

`settings` configuration object#

Environment variables for Strapi applications before `v4.6.2`#

Database connections using `connectionString`#

`connection` configuration object#

`settings` configuration object#

Environment variables for Strapi applications before `v4.6.2`#

Database connections using `connectionString`#