Skip to main content

数据库配置

🌐 Database configuration

Page summary:

/config/database 定义了连接、客户端和连接池。Strapi v4 和 v5 支持 SQLite、MySQL、MariaDB 和 PostgreSQL。不支持 MongoDB 和其他 NoSQL 数据库。NoSQL 支持仅存在于 Strapi v3。

/config/database.js|ts 文件用于定义将用于存储应用内容的数据库连接。

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

Supported databases

Strapi支持以下数据库：

数据库推荐最低
MySQL8.48.0
MariaDB11.410.3
PostgreSQL17.014.0
SQLite33

Strapi 不支持 MongoDB（或任何 NoSQL 数据库），也不支持任何“云原生”数据库（例如 Amazon Aurora、Google Cloud SQL 等）。

🌐 Strapi does not support MongoDB (or any NoSQL databases), nor does it support any "Cloud Native" databases (e.g., Amazon Aurora, Google Cloud SQL, etc.).

Warning

Strapi 应用不适用于连接到预先存在的数据库，即不是由 Strapi 应用创建的数据库，也不适用于连接到 Strapi v3 数据库。Strapi 团队不会支持这种尝试。尝试连接到不受支持的数据库可能，并且很可能会，导致数据丢失。

配置结构​

🌐 Configuration structure

/config/database.js|ts 文件接受两个主要的配置对象：

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

connection 配置对象​

🌐 connection configuration object

参数描述类型默认
client用于创建连接的数据库客户端。
可接受以下值：
  • sqlite 用于 SQLite 数据库
  • postgres 用于 PostgreSQL 数据库
  • mysql 用于 MySQL 数据库
String-
connection数据库连接信息Object-
debug显示数据库交互和错误。Booleanfalse
useNullAsDefault

可选，仅用于 SQLite		使用 NULL 作为默认值Booleantrue
pool

可选		数据库连接池选项Object-
acquireConnectionTimeout

可选		在获取连接时，knex 在抛出超时错误之前等待的时间（以毫秒为单位）Integer60000
Note

Strapi 仅支持以下客户端值，并且会在将配置传递给 Knex 之前自动将 client 值重写为以下选项：

🌐 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 值实际使用的包
sqlitebetter-sqlite3
mysqlmysql2
postgrespg

连接参数​

🌐 Connection parameters

./config/database.js（对于 TypeScript 为 ./config/database.ts）中找到的 connection.connection 对象用于传递数据库连接信息，并接受以下参数：

🌐 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:

参数描述类型
connectionString数据库连接字符串。设置时，会覆盖其他 connection.connection 属性。要禁用请使用空字符串：''。
在 v4.6.2+ 中可用		String
host数据库主机名。默认值：localhost。String
port数据库端口Integer
database 或 filename数据库名称或文件名。
  • 对于 MySQL 或 PostgreSQL，使用 database 键（配合 host、port 等）。
  • 对于 SQLite，只需提供指向数据库文件的 filename。
String
user用于建立连接的用户名String
password用于建立连接的密码String
timezone设置本地时间的默认行为。默认值：utc Timezone optionsString
schema设置默认数据库模式。仅用于 Postgres 数据库。String
ssl用于 SSL 数据库连接。
使用对象将证书文件作为字符串传递。		Boolean 或 Object
Note

根据所使用的数据库客户端，可以设置更多参数（例如，针对 mysql的charset和collation）。请查阅数据库客户端文档以了解可用的参数，例如 pg、 mysql和 better-sqlite3 文档。

Tip

connection 对象被传递给 Knex。如果 Knex 支持本页面未列出的其他选项（例如用于短期凭证的 expirationChecker），你可以在此处添加它们。

🌐 The connection object is passed to Knex. If Knex supports additional options that are not listed on this page (for example expirationChecker for short-lived credentials), you can add them here.

数据库连接池选项​

🌐 Database pooling options

./config/database.js（或 TypeScript 的 ./config/database.ts）中可选找到的 connection.pool 对象用于传递 Tarn.js 数据库连接池选项，并接受以下参数：

Caution

在使用 Docker 时，将池 min 的值更改为 0，因为 Docker 会杀死任何空闲连接，使得无法保持与数据库的任何开放连接（有关更多信息，请参见 Knex.js 使用的 Tarn.js pool 设置）。

参数描述类型默认
min要保持的最少数据库连接数Integer2
max数据库保持连接的最大数量Integer10
acquireTimeoutMillis数据库连接尝试超时前的时间（毫秒）Integer60000
createTimeoutMillis创建查询尝试超时前的毫秒数Integer30000
destroyTimeoutMillis在销毁查询尝试超时前的毫秒数Integer5000
idleTimeoutMillis在销毁空闲数据库连接之前的毫秒数Integer30000
reapIntervalMillis检查并销毁空闲数据库连接的时间（毫秒）Integer1000
createRetryIntervalMillis在重试失败的创建操作之前空闲的毫秒数Integer200
afterCreate当连接池获取新连接时执行自定义逻辑的回调函数。

更多信息请参见 Knex.js documentation		Function-

settings 配置对象​

🌐 settings configuration object

./config/database.js（或 TypeScript 的 ./config/database.ts）中找到的 settings 对象用于配置 Strapi 特定的数据库设置，并接受以下参数：

🌐 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:

参数描述类型默认
forceMigration允许模式同步删除不再属于内容类型模式的表、列、索引和外键。设置为 false 可跳过所有删除操作。Booleantrue
runMigrations在启动时运行 /database/migrations 中找到的迁移文件。无论此设置如何，Strapi 自身的内部迁移和模式同步都会运行。Booleantrue
useTypescriptMigrations在构建目录中查找迁移文件，而不是在源目录中查找，这样 TypeScript 迁移才会被执行。参见 使用 TypeScript 代码处理迁移。Booleanfalse
poolTimeoutDiagnostics在连接池获取超时错误中添加池状态、事件循环延迟和阶段信息，同时在池持续超时时记录周期性警告。设置为 false 可保持 Knex 原始错误和信息不变。参见 连接池超时。Booleantrue
Caution

尽管名字是 forceMigration，它并不控制迁移是否运行，这正是 runMigrations 所做的。它控制的是是否允许模式同步删除数据库对象。将它设置为 false 可以防止数据丢失，但模式同步仍会将新模式记录为参考，所以被跳过删除的表将不再被 Strapi 跟踪，并且如果你之后把该参数设回 true，它也不会被删除。详见 数据库迁移。

🌐 Despite its name, forceMigration does not control whether migrations run, which is what runMigrations does. It controls whether the schema sync is allowed to drop database objects. Setting it to false prevents data loss, but the schema sync still records the new schema as the reference, so a table whose deletion was skipped is no longer tracked by Strapi and is not dropped if you later set the parameter back to true. See database migrations.

连接池超时​

🌐 Connection pool timeouts

当 Knex（通过 Tarn.js）在 acquireConnectionTimeout 或 pool.acquireTimeoutMillis（取较小值）过去之前无法获取数据库连接时，它会抛出一个 KnexTimeoutError。除非 settings.poolTimeoutDiagnostics 是 false，否则 Strapi 会在错误信息中附上指向本节的链接。它还会附加一个 error.details 对象，描述当时的连接池情况。错误的类、名称和底层堆栈保持不变。

🌐 When Knex (through Tarn.js) cannot acquire a database connection before acquireConnectionTimeout or pool.acquireTimeoutMillis elapses, whichever is smaller, it throws a KnexTimeoutError. Unless settings.poolTimeoutDiagnostics is false, Strapi appends a link to this section to the error's message. It also attaches an error.details object describing the pool at that moment. The error's class, name, and underlying stack stay unchanged.

Strapi 还会记录一个警告块，在连接池持续超时的情况下，最多每 30 秒记录一次。无论是 error.details 还是警告，都不包含 SQL 语句或查询参数。

🌐 Strapi also logs a warning block, at most once every 30 seconds while the pool keeps timing out. Neither error.details nor the warning includes SQL statements or query parameters.

[database] connection pool timeout: waited 1523 ms for a connection (acquire timeout 1500 ms)
  - connections: 2 in use, 0 free, max 2, min 0
  - waiting for a connection: 37, connections being opened: 0
  - reason reported by the pool: operation timed out for an unknown reason
  - event loop delay over the last 11 s: max 323 ms, p99 41 ms
  - phase runtime, host api-7f9c, pid 981242
See https://strapi.nodejs.cn/cms/configurations/database#connection-pool-timeouts.

error.details 结构​

🌐 error.details structure

键描述类型
code总是 DB_POOL_ACQUIRE_TIMEOUT。String
waitedMs调用者等待 Knex 放弃前的时间长度。Number
acquireTimeoutMsKnex 应用的有效超时时间。Number
acquireConnectionTimeout配置的 connection.acquireConnectionTimeout，在设置时使用。Number
poolAcquireTimeoutMillis配置的 connection.pool.acquireTimeoutMillis，当设置时。Number
pool超时时的池计数：used、free、max、min、pendingAcquires、pendingCreates。Object
poolReason矿池报告失败尝试的原因，例如驱动错误，或者当矿池无法说明原因时为 "operation timed out for an unknown reason"。String
eventLoopDelay过去 30 到 60 秒观察到的事件循环延迟：maxMs、p99Ms、windowMs。Object
phase超时发生的生命周期阶段：boot、runtime、schema sync 或 migration <name>。String
hostname看到超时的进程的主机名。String
pid看到超时的进程的进程ID。Number

解读诊断结果​

🌐 Interpreting the diagnostics

诊断陈述的是事实，从不说明原因。常见模式：

🌐 The diagnostics state facts and never name a cause. Common patterns:

场景诊断显示
连接池饱和（请求激增，或者长时间运行的查询）pool.used 在 max 附近，并且 pendingAcquires 数量很高。
数据库拒绝或无法接受连接poolReason 包含驱动错误，例如连接被拒绝或认证失败。
Node.js 进程资源不足即使连接池有空闲连接，eventLoopDelay.maxMs 和 eventLoopDelay.p99Ms 仍然很高。
启动或迁移期间超时phase 是 boot、schema sync 或 migration <name> 而不是 runtime。

GraphQL 响应​

🌐 GraphQL responses

GraphQL API 返回的意外错误不再将内部错误的 name、message 和 details（包括上面的池超时诊断信息）复制到响应中。现在它返回与 REST API 相同的通用 Internal Server Error。完整的错误及诊断信息仍然会在服务器端记录。自定义解析器如果抛出一个普通的 Error 来给客户端返回信息，现在应该改为从 @strapi/utils 抛出 ApplicationError。

🌐 An unexpected error returned by the GraphQL API no longer copies the internal error's name, message, and details (including the pool timeout diagnostics above) into the response. It now returns the same generic Internal Server Error as the REST API. The full error, diagnostics included, is still logged server-side. A custom resolver that throws a plain Error to return a message to clients should throw an ApplicationError from @strapi/utils instead.

配置示例​

🌐 Configuration examples

./config/database.js
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,
  },
});
Caution

Strapi 已经注意到有关 服务器 SSL 支持 的问题。为了修复它，你必须将 ssl:{} 对象设置为布尔值以禁用它。具体示例如下：

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

请注意，如果你需要客户端 SSL CA 验证，你将需要使用 fs 模块中的 ssl:{} 对象将你的 CA 证书转换为字符串。你可以参见下面的示例：

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

示例：使用 AWS RDS IAM 认证（动态密码令牌）的 PostgreSQL

Knex 支持短期凭证，通过让你将 connection.connection 作为函数提供，并通过 expirationChecker 检查令牌是否需要续订。

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

./config/database.ts
import { Signer } from '@aws-sdk/rds-signer';
import type { Core } from '@strapi/strapi';

export default ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Database => {
  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,
        };
      },
    },
  };
};
Note

AWS RDS IAM 认证需要 SSL。请参阅 AWS documentation 获取所需的证书包和 SSL 参数。

数据库中的配置​

🌐 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 (字符串)：设置你希望存储数据的环境。默认是当前环境（如果你的配置与环境无关，可以为空字符串）。
  • type（字符串）：设置你的配置是用于 api、plugin 还是 core。默认是 core。
  • name (字符串)：如果 type 是 api 或 plugin，你必须设置插件或 API 名称。
  • key（字符串，必填）：你想要存储的键的名称。
// 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（任意，必填）：你想要存储的值。
// 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

一些云服务提供商会发放短期有效的数据库凭证，这些凭证在固定时间后会过期。例如，AWS RDS 的 IAM 令牌有效期为 15 分钟；GCP Cloud SQL 的 IAM 令牌也类似过期；HashiCorp Vault 可以按计划轮换密钥。在 .env 中使用静态密码会导致连接池在令牌过期后回收空闲连接时出现间歇性连接失败。

🌐 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 通过 Knex 的连接函数模式支持动态凭证。你可以传入一个同步或异步函数给 connection.connection，而不是普通的连接对象。Knex 每次需要打开新的数据库连接时都会调用这个函数，从而确保连接池总是使用最新的凭证。这种模式适用于 PostgreSQL 和 MySQL/MariaDB。从 Strapi v5.51.0 开始，TypeScript 类型正式支持为 connection.connection 使用同步和异步函数。

🌐 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.

Tip

在你函数返回的对象中包含一个 expirationChecker 属性。Knex 在从连接池重用连接之前会调用它；如果它返回 true，Knex 会丢弃现有连接，然后再次调用你的函数来获取新的凭据。

🌐 Include an expirationChecker property in the object returned by your function. Knex calls this before reusing a connection from the pool; if it returns true, Knex discards the existing connection and calls your function again to obtain fresh credentials.

使用 AWS RDS IAM 身份验证的 MySQL/MariaDB​

🌐 MySQL/MariaDB with AWS RDS IAM authentication

下面的例子展示了每次连接池打开新的 MySQL 连接时，都会从 AWS SDK 获取一个新的 IAM 认证令牌。对于 PostgreSQL 的对应示例，请参见上面配置示例中的 PostgreSQL + AWS RDS IAM 认证示例。

🌐 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.

./config/database.js
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,
        };
      },
    },
  };
};
Note

AWS RDS 的 IAM 身份验证需要在 RDS 实例上启用 SSL 和 IAM 数据库身份验证。请参考 AWS documentation 获取所需的证书包和设置说明。

数据库配置中的环境变量​

🌐 Environment variables in database configurations

Strapi 版本 v4.6.2 及更高版本在 ./config/database.js 或 ./config/database.ts 文件中包含数据库配置选项。当创建新项目时，根据在项目创建过程中选择的数据库，会自动将值为 mysql、postgres 或 sqlite 的环境变量 DATABASE_CLIENT 添加到 .env 文件中。此外，连接到本地开发数据库所需的所有环境变量也会添加到 .env 文件中。以下是生成的配置文件示例：

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

以下是每个可能数据库对应的 .env 文件数据库相关键的示例：

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

terminal

# 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

v4.6.2 之前 Strapi 应用的环境变量​

🌐 Environment variables for Strapi applications before v4.6.2

如果你使用早于 v4.6.2 的版本启动了你的项目，你可以按照以下程序转换你的 database.js|database.ts 配置文件：

🌐 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:

  1. 将你的应用更新到 v4.6.2 或更高版本。请参阅 升级 文档。
  2. 用上面的 JavaScript 或 TypeScript 代码替换你的 ./config/database.js 或 ./config/database.ts 文件的内容。
  3. 将前面代码示例中的环境变量添加到你的 .env 文件中。
  4. （可选）添加额外的环境变量，例如 DATABASE_URL 以及 ssl 对象的属性。
  5. 保存更改并重新启动你的应用。
Caution

不要覆盖环境变量：HOST、PORT、APP_KEYS、API_TOKEN_SALT 和 ADMIN_JWT_SECRET。

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

使用 connectionString 的数据库连接​

🌐 Database connections using connectionString

许多托管数据库解决方案使用属性 connectionString 将数据库连接到应用。Strapi v4.6.2 及更高版本包括 connectionString 属性。connectionString 是 connection.connection 对象中所有数据库属性的串联。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:

  • 覆盖其他 connection.connection 属性，例如 host 和 port，
  • 可以通过将属性设置为空字符串来禁用：''。

按环境进行数据库管理​

🌐 Database management by environment

Strapi 应用的开发通常包括在本地开发环境中使用本地开发数据库（例如 SQLite）进行自定义。当应用准备好部署到其他环境（如生产或预发布环境）时，应用会使用不同的数据库实例部署，通常是 MySQL、MariaDB 或 PostgreSQL。数据库环境变量允许你切换所连接的数据库。要切换数据库连接：

🌐 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:

  • 为 MySQL、MariaDB 和 PostgreSQL 设置 DATABASE_CLIENT 和 DATABASE_URL 的最小值，
  • 或者为 SQLite 设置 DATABASE_CLIENT 和 DATABASE_FILENAME 的最小值。

对于已部署的应用版本，数据库环境变量应存储在存储其他密钥信息的地方。下表给出了数据库环境变量应存储的位置示例：

🌐 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:

托管选项环境变量存储
虚拟专用服务器/虚拟机（例如 AWS EC2）ecosystem.config.js 或 .env
DigitalOcean 应用平台Environment Variables 表
HerokuConfig vars 表

数据库安装​

🌐 Databases installation

Strapi 让你可以为你的项目选择最合适的数据库。Strapi 支持 MySQL、MariaDB、PostgreSQL 和 SQLite。

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

SQLite​

SQLite 是默认的（参见 快速入门指南）且推荐的数据库，用于快速在本地创建应用。

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

在创建应用时安装 SQLite​

🌐 Install SQLite during application creation

使用以下命令之一：

🌐 Use one of the following commands:

terminal
yarn create strapi-app my-project --quickstart

这将创建一个新项目并在浏览器中启动它。

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

手动安装 SQLite​

🌐 Install SQLite manually

在终端中，运行以下命令：

🌐 In a terminal, run the following command:

terminal
yarn add better-sqlite3

将以下代码添加到你的 /config/database.ts|js 文件中：

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

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

PostgreSQL​

将 Strapi 连接到 PostgreSQL 数据库时，数据库用户需要 SCHEMA 权限。虽然数据库管理员默认具有此权限，但为 Strapi 应用专门创建的新数据库用户将不具备该权限。这会导致在尝试加载管理员控制台时出现 500 错误。

🌐 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.

要创建具有 SCHEMA 权限的新 PostgreSQL 用户，请使用以下步骤：

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

terminal
# 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;
On this page