数据库连接故障排查

启动时数据库连接失败

现象： dab start 启动失败，日志中出现网络连接错误或认证失败信息。

通用排查步骤：

1. 确认数据库服务正在运行且可访问。
2. 用数据库原生客户端（sqlcmd、psql、mysql）测试同一连接字符串。
3. 检查连接字符串格式——不同数据库的参数名不同。
4. 确认网络可达——容器环境中需特别注意 host.docker.internal 或容器网络。

SQL Server

连接失败：网络相关错误

现象： A network-related or instance-specific error occurred while establishing a connection to SQL Server。

常见原因与解决：

原因	解决
服务器地址或端口错误	确认 Server=host,port ——SQL Server 默认端口 1433
防火墙阻止	检查数据库服务器的防火墙规则，允许数据墙DBW 的 IP 访问 1433 端口
Docker 容器网络	宿主机访问容器用 localhost,1433，容器间访问用容器名或 Docker 网络
加密要求不满足	添加 TrustServerCertificate=true（开发环境）或配置正式 TLS 证书

登录失败

现象： Login failed for user 'xxx'。

排查步骤：

1. 确认用户名和密码正确——注意 User Id（两个词）中的空格。
2. 确认数据库中存在该用户且拥有对应数据库的访问权限。
3. 如果使用 Windows 集成认证，连接字符串需包含 Trusted_Connection=True 并在 Windows 环境下运行。

Docker 容器中连接宿主机 SQL Server

在 Docker 容器中运行时，连接宿主机上的 SQL Server 使用 host.docker.internal：

Server=host.docker.internal,1433;Database=mydb;User Id=sa;Password=pwd;TrustServerCertificate=true;

Linux Docker 可能需要添加 --add-host host.docker.internal:host-gateway。

PostgreSQL

连接失败

现象： connection refused 或 no pg_hba.conf entry。

常见原因与解决：

原因	解决
PostgreSQL 未监听正确地址	确认 postgresql.conf 中 listen_addresses 包含 '*' 或数据墙DBW 的 IP
pg_hba.conf 未允许连接	添加条目允许数据墙DBW 的 IP 或网段
端口错误	PostgreSQL 默认端口 5432，格式 Host=host;Port=5432

认证失败

现象： password authentication failed for user。

排查步骤：

1. 确认用户名和密码正确。PostgreSQL 用户名默认区分大小写。
2. 确认 pg_hba.conf 中的认证方法（md5、scram-sha-256）与提供的密码方式匹配。
3. 注意连接字符串参数格式：User ID（两个词，空格分隔），不是 UserId 或 UserID。

SSL 错误

现象： SSL 相关的连接被拒错误。

解决：

• 添加 SSL Mode=Prefer 允许非 SSL 连接（开发环境）。
• 生产环境使用 SSL Mode=Require 配合正式证书。
• 注意 SSL Mode 空格分隔，与 SQL Server 和 MySQL 格式不同。

MySQL

连接失败

现象： Unable to connect to any of the specified MySQL hosts。

排查步骤：

1. 确认主机和端口正确——MySQL 默认端口 3306。
2. 确认 MySQL 用户允许从数据墙DBW 的主机 IP 连接（GRANT ... TO 'user'@'host'）。
3. 连接字符串格式：Server=host;Port=3306;Database=mydb;User=root;Password=pwd。

认证插件不兼容

现象： Authentication plugin 'caching_sha2_password' cannot be loaded。

解决：

• MySQL 8 默认使用 caching_sha2_password。确保 MySqlConnector 驱动版本支持。
• 或修改用户使用 mysql_native_password：ALTER USER 'user'@'host' IDENTIFIED WITH mysql_native_password BY 'password'。

数据类型错误

现象： geometry、json、set、time 类型的字段导致启动错误或运行时异常。

说明： MySQL 的 geometry、json、set 和 time 类型不被数据墙DBW 支持。如果表中有这些列，需在 fields.exclude 中排除，或通过视图只选择支持的列类型。

所有数据库通用的排查方法

验证连接字符串

用数据库原生工具测试同一连接字符串是否能成功连接：

# SQL Server
sqlcmd -S host,1433 -U user -P password -d mydb -Q "SELECT 1"

# PostgreSQL
psql "Host=host;Port=5432;Database=mydb;User ID=user;Password=pwd" -c "SELECT 1"

# MySQL
mysql -h host -P 3306 -u user -p -D mydb -e "SELECT 1"

如果原生工具也无法连接，问题在数据库端而非数据墙DBW。

检查日志

调高数据墙DBW 日志级别获取更详细的连接错误信息：

dab start --LogLevel Debug

运行健康检查

启动后访问 /health 端点确认数据库连接状态：

curl http://localhost:5000/health

连接池问题

高并发场景下如果请求排队，检查数据库连接池是否耗尽：

• 增加 Max Pool Size（SQL Server）/MaxPoolSize（PostgreSQL）/MaximumPoolSize（MySQL）。
• 确认 Pooling 未被设为 false。

下一步

• REST 故障排查 — REST API 相关问题。
• 配置故障排查 — 配置文件错误。