数据库 Database

Strapi 提供单一入口点文件来配置其数据库。

./config/database.js 文件（或 TypeScript 的 ./config/database.ts 文件）用于定义将用于存储应用程序内容的数据库连接。

Strapi 应用程序不应连接到预先存在的数据库、不是由 Strapi 应用程序创建的数据库或连接到 Strapi v3 数据库。Strapi 团队不支持此类尝试。尝试连接到不受支持的数据库可能会导致数据丢失。

支持的数据库

Strapi v4.6.2 为数据库配置文件引入了一种新格式，允许使用环境变量设置所有数据库配置属性。只有在 v4.6.2 版本之后创建的新项目才会包含新配置，但是，早期项目可以通过手动修改 ./config/database.js 或 ./config/database.ts 并更新 .env 文件来利用新配置。请参阅数据库配置中的环境变量

配置结构

./config/database.js（或 TypeScript 的 ./config/database.ts）接受 2 个主要配置对象：

connection 用于传递给 Knex.js 的数据库配置选项
settings 用于 Strapi 特定的数据库设置

`connection` 配置对象

参数	说明	类型	默认
`client`	数据库客户端创建连接。接受以下值：对于 SQLite 数据库： `sqlite3` `better-sqlite3` 对于 PostgreSQL 数据库：`postgres` 对于 MySQL 数据库： `mysql` `mysql2`（请参阅其他详细信息)	`String`	-
`connection`	数据库连接信息	`Object`	-
`debug`	显示数据库交换和错误。	`Boolean`	`false`
`useNullAsDefault` 可选，仅适用于 SQLite	使用 `NULL` 作为默认值	`Boolean`	`true`
`pool` 可选	数据库池选项	`Object`	-
`acquireConnectionTimeout` 可选	获取连接时，knex 在抛出超时错误之前将等待多长时间（以毫秒为单位）	`Integer`	`60000`

如果项目中有该包，Strapi 会将“sqlite”的“client”值修改为“better-sqlite3”，否则修改为“sqlite3”。

连接参数

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

参数	描述	类型
`connectionString`	数据库连接字符串。设置后，它将覆盖其他 `connection.connection` 属性。要禁用，请使用空字符串：`''`。在 Strapi v4.6.2+ 中可用	`String`
`host`	数据库主机名。默认值：`localhost`。	`String`
`port`	数据库端口	`Integer`
`database`	数据库名称。	`String`
`user`	用于建立连接的用户名	`String`
`password`	用于建立连接的密码	`String`
`timezone`	设置本地时间的默认行为。默认值：`utc` 时区选项	`String`
`schema`	设置默认数据库架构。仅适用于 Postgres DB。	`String`
`ssl`	用于 SSL 数据库连接。使用对象将证书文件作为字符串传递。	`Boolean` 或 `Object`

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

数据库池选项

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

使用 Docker 时，将池 min 值更改为 0，因为 Docker 将终止任何空闲连接，从而无法保持与数据库的任何打开连接（有关更多信息，请参阅 Knex.js 使用的 Tarn.js 池设置）。

参数	说明	类型	默认
`min`	保持活动的数据库连接的最小数量	`Integer`	`2`
`max`	保持活动数据库连接的最大数量	`Integer`	`10`
`acquireTimeoutMillis`	数据库连接尝试超时前的时间（以毫秒为单位）	`Integer`	`60000`
`createTimeoutMillis`	创建查询尝试超时前的时间（以毫秒为单位）	`Integer`	`30000`
`destroyTimeoutMillis`	销毁查询尝试超时前的时间（以毫秒为单位）	`Integer`	`5000`
`idleTimeoutMillis`	销毁空闲数据库连接前的时间（以毫秒为单位）	`Integer`	`30000`
`reapIntervalMillis`	检查要销毁的空闲数据库连接的时间（以毫秒为单位）	`Integer`	`1000`
`createRetryIntervalMillis`	在重试失败的创建操作之前处于空闲状态的时间（以毫秒为单位）	`Integer`	`200`
`afterCreate`	当池获取新连接时执行自定义逻辑的回调函数。有关更多信息，请参阅 Knex.js 文档	`Function`	-

`settings` 配置对象

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

参数	说明	类型	默认
`forceMigration`	启用或禁用强制数据库迁移。	`Boolean`	`true`
`runMigrations`	启用或禁用启动时运行的数据库迁移。	`Boolean`	`true`

Configuration examples

PostgreSQL

./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,
  },
})

Strapi 知道存在与 服务器的 SSL 支持 有关的问题。为了修复它，您必须将 ssl:{} 对象设置为布尔值以禁用它。例如，请参见以下示例：

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

请注意，如果您需要客户端 SSL CA 验证，则需要使用 ssl:{} 对象和 fs 模块将您的 CA 证书转换为字符串。您可以在下面看到一个示例：

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

MySQL/MariaDB

./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,
  },
})

SQLite

./config/database.js

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

数据库中的配置

配置文件不适用于多服务器。要更新生产中的配置，您可以使用数据存储来获取和设置设置。

获取设置

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

数据库配置中的环境变量

Strapi 版本 v4.6.2 及更高版本在 ./config/database.js 或 ./config/database.ts 文件中包括数据库配置选项。创建新项目时，环境变量 DATABASE_CLIENT 的值将自动添加到 .env 文件中，具体取决于您在项目创建期间选择的数据库。此外，连接到本地开发数据库所需的所有环境变量也将添加到 .env 文件中。以下是生成的配置文件的示例：

JavaScript

const path = require('node: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),
    },
  }
}

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

bash

MySQL or MariaDB

bash

# 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

如果您收到 ER_ACCESS_DENIED_ERROR 消息，并且 .env 文件中的 DATABASE_PASSWORD 值包含特殊字符，请尝试用单引号将密码括起来。例如，DATABASE_PASSWORD=example-i-had-special-chars-like-# 应变为 DATABASE_PASSWORD='example-i-had-special-chars-like-#'。

`v4.6.2` 之前 Strapi 应用程序的环境变量

如果您使用 v4.6.2 之前的版本启动项目，则可以按照以下步骤转换 database.js|database.ts 配置文件：

将您的应用程序更新到 v4.6.2 或更高版本。有关需要特定修复的任何重大更改，请参阅更新和迁移部分。
使用前面的 JavaScript 或 TypeScript 代码替换 ./config/database.js 或 ./config/database.ts 文件的内容。
将前面代码示例中的环境变量添加到 .env 文件中。
（可选）添加其他环境变量，例如 DATABASE_URL 和 ssl 对象的属性。
保存更改并重新启动应用程序。
请勿覆盖环境变量：HOST、PORT、APP_KEYS、API_TOKEN_SALT 和 ADMIN_JWT_SECRET。

使用 `connectionString` 的数据库连接

许多托管数据库解决方案使用属性 connectionString 将数据库连接到应用程序。Strapi v4.6.2 及更高版本包含 connectionString 属性。 connectionString 是 connection.connection 对象中所有数据库属性的串联。connectionString：

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

按环境管理数据库

Strapi 应用程序的开发通常包括在本地开发环境中使用本地开发数据库（例如 SQLite）进行自定义。当应用程序准备好用于另一个环境（例如生产或暂存）时，应用程序将使用不同的数据库实例进行部署，通常是 MySQL、MariaDB 或 PostgreSQL。数据库环境变量允许您切换附加的数据库。要切换数据库连接：

为 MySQL、MariaDB 和 PostgreSQL 设置最少的 DATABASE_CLIENT 和 DATABASE_URL，
或为 SQLite 设置最少的 DATABASE_CLIENT 和 DATABASE_FILENAME。

对于已部署的应用程序版本，数据库环境变量应存储在存储其他机密的任何位置。下表给出了应存储数据库环境变量的位置示例：

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

数据库安装指南

Strapi 为您提供了为您的项目选择最合适的数据库的选项。Strapi 支持 PostgreSQL、SQLite、MySQL 和 MariaDB。

以下文档介绍了如何在本地安装数据库：

SQLite 安装指南，
PostgreSQL（即将推出），
MySQL/MariaDB（即将推出）。

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

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

shell

# 使用安全密码创建新的数据库用户
$ CREATE USER my_strapi_db_user WITH PASSWORD 'password';
# 以 PostgreSQL 管理员身份连接到数据库
$ \c my_strapi_db_name admin_user
# 向用户授予架构权限
$ GRANT ALL ON SCHEMA public TO my_strapi_db_user;

替代数据库驱动程序包

除了 client 值为 'postgres'、'sqlite' 和 'mysql' 之外，Strapi 还允许安装并希望使用该包的用户使用 client 值为 'mysql2'。

mysql2 是 MySQL v8+ 中默认使用的 caching_sha2_password 身份验证方法所必需的。如果在使用 mysql 驱动程序时收到 "ER_NOT_SUPPORTED_AUTH_MODE" 错误，请尝试将 mysql2 包添加到您的项目中。然后，您应该从连接配置中删除已弃用的 connectionString 参数，转而使用 user 和 password 值。

配置结构

connection 配置对象

连接参数

数据库池选项

settings 配置对象

Configuration examples

PostgreSQL

MySQL/MariaDB

SQLite

数据库中的配置

获取设置

Set settings

数据库配置中的环境变量

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

使用 connectionString 的数据库连接

按环境管理数据库

数据库安装指南

替代数据库驱动程序包

`connection` 配置对象

`settings` 配置对象

`v4.6.2` 之前 Strapi 应用程序的环境变量

使用 `connectionString` 的数据库连接