接入关系型数据库

数据墙DBW 通过配置文件中的 data-source 块来连接你的数据库。无论是本地开发库、测试环境还是生产库，接入方式统一且简单。

TIP

还没有数据库？ 可以用 Docker 快速启动一个本地实例：

# SQL Server
docker run --name dab-mssql --env "ACCEPT_EULA=Y" --env "MSSQL_SA_PASSWORD=P@ssw0rd1" --publish 1433:1433 --detach mcr.microsoft.com/mssql/server:2025-latest

# PostgreSQL
docker run --name dab-postgres --env "POSTGRES_PASSWORD=P@ssw0rd1" --publish 5432:5432 --detach postgres:16

# MySQL
docker run --name dab-mysql --env "MYSQL_ROOT_PASSWORD=P@ssw0rd1" --publish 3306:3306 --detach mysql:8

NOTE

如果你使用 dab init 命令初始化项目，该命令会自动生成 data-source 配置块，无需手动编写。以下内容适用于需要手动定制配置或理解配置结构的场景。

配置数据源

data-source 至少需要两个字段——数据库类型和连接字符串：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost,1433;Database=todos;User Id=sa;Password=P@ssw0rd1;TrustServerCertificate=true;"
  }
}

database-type 支持三种关系型数据库：

值	数据库
mssql	SQL Server
postgresql	PostgreSQL
mysql	MySQL

连接字符串格式

不同数据库的连接字符串格式有所不同，以下是常用示例：

SQL Server

Server=<host>,<port>;Database=<db>;User Id=<user>;Password=<pwd>;TrustServerCertificate=true;

如果连接本地 Docker 实例，端口默认是 1433，用户名为 sa。

NOTE

TrustServerCertificate=true 适用于开发环境。生产环境应配置正式的 TLS 证书，或使用 Encrypt=true 搭配受信任的证书颁发机构。

PostgreSQL

Host=<host>;Port=5432;Database=<db>;User ID=<user>;Password=<pwd>;

MySQL

Server=<host>;Port=3306;Database=<db>;User=<user>;Password=<pwd>;

用环境变量保护密码

将密码直接写在配置文件中既不安全也不利于多环境部署。推荐使用 @env() 语法引用环境变量：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

启动服务前，设置好对应的环境变量：

# Windows (PowerShell)
$env:SQL_CONNECTION_STRING = "Server=localhost;Database=todos;..."

# Linux / macOS
export SQL_CONNECTION_STRING="Server=localhost;Database=todos;..."

同一份配置文件在不同环境中只需使用不同的环境变量值，无需修改配置本身。

数据库选项

options 字段用于配置数据库特定的行为。常用的选项包括：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONN_STR')",
    "options": {
      "set-session-context": true
    }
  }
}

选项	适用数据库	说明
set-session-context	SQL Server	将 JWT 令牌中的声明信息注入数据库会话上下文，支持行级安全策略中使用 @claims 引用

大多数场景不需要设置 options，使用默认值即可正常工作。

连接多个数据库

如果需要同时从多个数据库暴露数据，可以通过 data-source-files 引用额外的配置文件：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('MAIN_DB')"
  },
  "data-source-files": ["config-crm.json", "config-erp.json"]
}

每个引用的配置文件各自定义自己的 data-source 和 entities。所有实体在同一个 API 入口下对外暴露，调用方不需要关心数据来自哪个数据库。

数据源健康检查

可以为数据源配置健康检查，让容器编排平台或监控系统定期验证数据库连接状态：

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "main-db",
      "threshold-ms": 1000
    }
  }
}

健康检查会在服务运行时定期执行，结果可通过 /health 端点查询。

下一步

数据库连接配置完成后，继续阅读启动并验证服务，运行 dab start 并测试你的 API。