How to troubleshoot a database connection failure如何排查数据库连接故障
Database connection troubleshooting is the process of identifying the first layer that fails between an application and a usable database session. Start from the runtime that reports the error, preserve the exact timestamp and message, and test configuration, name resolution, route, TCP, TLS, authentication, database selection, pooling and one minimal read-only operation in that order.数据库连接故障排查，是在应用与可用数据库会话之间找出首个失败层的过程。应从真正报错的运行时开始，保留准确时间与错误信息，并依次检查配置、名称解析、路由、TCP、TLS、认证、数据库选择、连接池和一次最小只读操作。
A port result is not a login result, and a successful login is not proof that the application can select the intended database or execute its workload. Record each observation before making a change. This keeps a DNS or firewall failure from becoming an unnecessary password reset, and keeps an authorization failure from becoming an unsafe network exception.端口结果不等于登录结果，登录成功也不能证明应用能够选择目标数据库或执行实际工作负载。应在变更前记录每层观察结果，避免把 DNS 或防火墙故障误处理为密码重置，也避免把授权问题误处理为不安全的网络放行。
The seven layers of database connectivity数据库连通性的七个层次
Most failures become easier to diagnose when the connection is treated as a sequence rather than a single event. A later layer cannot succeed when an earlier layer is broken.把连接看作一系列连续步骤，而不是单一事件，大多数故障都会更容易定位。前一层失败时，后一层不可能成功。
- Endpoint resolution端点解析DNS converts the configured hostname into the intended address. Split-horizon DNS, stale caches, VPN rules, and misspelled endpoints can send clients to the wrong place.DNS 把配置的主机名转换为目标地址。分域 DNS、过期缓存、VPN 规则和拼写错误都可能把客户端引向错误位置。
- Route and network boundary路由与网络边界The client needs a valid route through VPCs, subnets, peering, VPNs, proxies, or private links. A database can be healthy yet unreachable from the chosen source.客户端需要通过 VPC、子网、对等连接、VPN、代理或私有链路获得有效路由。数据库可能完全健康，却无法从当前来源访问。
- Firewall and port防火墙与端口Security groups, network ACLs, host firewalls, and egress policy must allow the actual database port in both required directions.安全组、网络 ACL、主机防火墙和出站策略必须允许真实数据库端口的必要双向流量。
- TLS handshakeTLS 握手The client and server must agree on encryption, certificate trust, hostname verification, and supported protocol versions.客户端与服务器必须在加密、证书信任、主机名验证及支持的协议版本上达成一致。
- Authentication身份验证The database validates a password, certificate, token, IAM identity, integrated login, or another supported credential method.数据库验证密码、证书、令牌、IAM 身份、集成登录或其他支持的凭据方式。
- Authorization and database selection授权与数据库选择A valid identity still needs permission to connect to the requested database, schema, warehouse, or service.身份有效并不代表有权访问目标数据库、Schema、Warehouse 或服务，还需要正确授权。
- Session and pool behavior会话与连接池行为Applications reuse connections through pools. Limits, stale sessions, leaks, and long transactions can fail requests even when a new manual connection works.应用通常通过连接池复用连接。连接上限、过期会话、连接泄漏和长事务都可能导致请求失败，即使手动新建连接可以成功。
Treat the connection string as input evidence, not the whole diagnosis把连接字符串作为输入证据，而不是全部诊断
For troubleshooting, extract only the effective endpoint, port, database or service, driver, TLS mode, authentication method and timeout settings. Configuration can be assembled from environment variables, secret stores, framework defaults and code, so the string visible in one file may not be what the failing process actually uses.排障时只需提取实际生效的端点、端口、数据库或服务、驱动、TLS 模式、认证方式和超时设置。配置可能由环境变量、密钥库、框架默认值与代码共同组装，因此某个文件中看到的字符串未必是故障进程真正使用的内容。
Resolved host, port, instance, service and database name.解析后的主机、端口、实例、服务与数据库名称。
Authentication type, TLS mode, certificate result and account class—never the secret itself.认证类型、TLS 模式、证书结果与账户类别，绝不包含秘密本身。
If the problem is parameter syntax, precedence or provider-specific formatting, use the database connection string examples page instead. This page uses the effective values only to decide which connection layer to test next.若问题属于参数语法、优先级或驱动专属格式，请转到数据库连接字符串示例页面。本页只使用实际生效值来决定下一步测试哪个连接层。
Use port evidence as one troubleshooting layer把端口证据作为排障中的一个层级
A documented default can help interpret configuration, but the deployed listener, managed endpoint or proxy may use another port. Confirm the value from the same effective configuration used by the application, then test from the same network and identity boundary. Do not scan unrelated hosts or broad port ranges.文档默认值可以帮助理解配置，但实际监听器、托管端点或代理可能使用其他端口。应从应用实际生效配置确认端口，并在相同网络与身份边界内测试；不要扫描无关主机或大范围端口。
| Observation观察结果 | What it supports可以支持的结论 | Next check下一步 |
|---|---|---|
| Timeout超时 | No TCP response within the test window测试窗口内没有 TCP 响应 | Route, firewall, endpoint and listener state路由、防火墙、端点与监听状态 |
| Refused拒绝连接 | The host responded but no listener accepted that address主机已响应，但该地址没有监听器接收 | Configured port, bind address and service status配置端口、绑定地址与服务状态 |
| TCP connectedTCP 已连接 | A listener accepted transport监听器接受了传输连接 | TLS, protocol, authentication and database selectionTLS、协议、认证与数据库选择 |
For a reference table and vendor-specific verification notes, continue with database port numbers.若需要端口参考表与厂商专属验证说明，请继续查看数据库端口号页面。
How to test database connectivity step by step如何逐步测试数据库连通性
Test from the failing application's network context whenever possible. A laptop, bastion, serverless function, container, and production application may follow different DNS, routes, and firewall policies.应尽可能从发生故障的应用网络环境进行测试。笔记本、跳板机、Serverless 函数、容器和生产应用可能使用不同的 DNS、路由与防火墙策略。
- Capture the exact failure记录准确错误Record timestamp, client environment, sanitized endpoint, driver version, timeout phase, and the complete error code. Do not reduce everything to “database down.”记录时间、客户端环境、脱敏端点、驱动版本、超时阶段和完整错误码，不要把所有问题都简化为“数据库宕机”。
- Verify endpoint and service state核实端点与服务状态Confirm the assigned host, port, database or service name, and whether the database is running and accepting remote sessions.确认分配的主机、端口、数据库或服务名，并确认数据库正在运行且允许远程会话。
- Resolve DNS from the client从客户端解析 DNSCompare the resolved address with the expected private or public endpoint. Check VPN and private-zone behavior.把解析地址与预期私有或公共端点进行比较，并检查 VPN 与私有 DNS Zone 行为。
- Test the assigned TCP endpoint测试指定 TCP 端点Use an authorized host and port from the same network path. A pass confirms socket reachability—not login or query readiness.从相同网络路径测试已授权主机和端口。通过只证明套接字可达，不代表登录或查询已经就绪。
- Validate TLS deliberately明确验证 TLSCheck required mode, certificate chain, hostname, expiry, protocol version, and whether the driver trusts the issuing CA.检查要求的模式、证书链、主机名、有效期、协议版本，以及驱动是否信任签发 CA。
- Test authentication with least privilege用最小权限测试身份验证Use a temporary or limited account. Distinguish invalid credentials from disabled accounts, expired tokens, and unsupported auth modes.使用临时或受限账号，区分凭据错误、账号禁用、令牌过期和认证模式不支持。
-
Verify database access with a harmless query用无害查询验证数据库访问Run the smallest supported health query, such as
SELECT 1, then verify the intended database and schema without modifying data.运行数据库支持的最小健康查询，例如SELECT 1，再验证目标数据库和 Schema，避免修改数据。 - Reproduce through the application pool通过应用连接池复现If manual login works, test the application's pool settings, secret source, runtime identity, concurrency, and stale-session handling.如果手动登录成功，应继续测试应用的连接池设置、密钥来源、运行时身份、并发和过期会话处理。
What each database connection result actually means每种数据库连接结果真正意味着什么
| Result结果 | Evidence可以证明 | Does not prove不能证明 |
|---|---|---|
| DNS resolvesDNS 解析成功 | The client obtained an address客户端获得了地址 | Route, port, or database availability路由、端口或数据库可用性 |
| TCP port reachableTCP 端口可达 | A listener accepted a network connection监听服务接受了网络连接 | TLS, credentials, permissions, or queriesTLS、凭据、权限或查询 |
| TLS succeedsTLS 成功 | Encrypted transport and trust rules agreed加密传输与信任规则达成一致 | Valid database identity or authorization数据库身份或授权有效 |
| Authentication succeeds身份验证成功 | The server accepted the identity服务器接受了该身份 | Access to the required schema or workload可以访问所需 Schema 或工作负载 |
| Health query succeeds健康查询成功 | A complete basic session worked基本会话完整成功 | Capacity, reliability, or production performance容量、可靠性或生产性能 |
Troubleshoot database connection failed errors排查数据库连接失败错误
| Symptom现象 | Likely layer可能层次 | Best next evidence下一项证据 |
|---|---|---|
| Host not found找不到主机 | DNS | Resolution result, suffix, VPN, private-zone record解析结果、DNS 后缀、VPN、私有 Zone 记录 |
| Connection refused / ECONNREFUSED连接拒绝 / ECONNREFUSED | Listener or active rejection监听服务或主动拒绝 | Service state, real port, binding, host firewall服务状态、真实端口、绑定、主机防火墙 |
| Connection timed out / ETIMEDOUT连接超时 / ETIMEDOUT | Route, policy, or stalled handshake路由、策略或握手停滞 | Security group, ACL, egress, route table, packet timing安全组、ACL、出站策略、路由表、数据包时间 |
| Certificate or hostname error证书或主机名错误 | TLS | Certificate chain, SAN, expiry, CA trust, TLS mode证书链、SAN、有效期、CA 信任、TLS 模式 |
| Access denied / login failed访问拒绝 / 登录失败 | Authentication身份验证 | Identity source, secret version, account state, auth method身份来源、密钥版本、账号状态、认证方式 |
| Database does not exist / permission denied数据库不存在 / 权限不足 | Selection and authorization选择与授权 | Database name, default database, grants, roles, schema mapping数据库名、默认数据库、授权、角色、Schema 映射 |
| Pool timeout / too many connections连接池超时 / 连接过多 | Pool and capacity连接池与容量 | Active/idle count, wait time, leak signals, DB connection limit活动/空闲数、等待时间、泄漏迹象、数据库连接上限 |
Connection timeout, query timeout, and pool timeout differ连接超时、查询超时和连接池超时并不相同
Connection timeout连接超时
Limits how long a new session may spend on resolution, routing, TCP, TLS, and login. Raising it can hide a network fault instead of fixing it.限制新会话在解析、路由、TCP、TLS 和登录阶段可以等待多久。单纯提高数值可能掩盖网络故障。
Query timeout查询超时
Limits statement execution after a session exists. Investigate plans, locks, workload, resource pressure, and result size.限制会话建立后的语句执行时间，应检查执行计划、锁、负载、资源压力和结果大小。
Pool acquisition timeout连接池获取超时
Limits how long a request waits for a reusable session. Measure pool occupancy, checkout duration, leaks, and database limits.限制请求等待可复用会话的时间，应测量连接池占用率、借用时长、泄漏和数据库上限。
Idle or lifetime limit空闲或生命周期限制
Retires old sessions before a proxy, firewall, credential rotation, or server closes them unexpectedly.在代理、防火墙、凭据轮换或服务器意外关闭旧会话前主动淘汰连接。
Choose pool size from concurrency, average checkout time, service replicas, and the database's total connection budget. If ten application replicas each open fifty sessions, the database must absorb up to five hundred connections—not fifty.连接池大小应根据并发量、平均借用时间、服务副本数和数据库总连接预算共同确定。如果十个应用副本各自打开五十个会话，数据库需要承受的上限是五百，而不是五十。
Secure database connections without breaking diagnosis在不妨碍诊断的前提下保护数据库连接
- Prefer private paths: use private subnets, peering, VPNs, or private endpoints instead of broad public exposure.优先私有路径：使用私有子网、对等连接、VPN 或私有端点，避免大范围公网暴露。
- Allowlist narrowly: authorize the application security group or smallest practical source range and actual port.严格白名单：只允许应用安全组或最小可行来源范围访问真实端口。
- Require verified encryption: encryption without certificate verification still permits avoidable trust risk.要求经过验证的加密：仅加密但不验证证书，仍会留下可避免的信任风险。
- Keep secrets out of code and URLs: retrieve credentials from a secret manager, rotate them, and redact diagnostic output.不要把密钥放进代码和 URL：从密钥管理器获取凭据，定期轮换，并对诊断输出脱敏。
- Use least privilege: a connectivity check does not need write, administration, or unrestricted schema access.使用最小权限：连通性检查不需要写入、管理或不受限制的 Schema 权限。
Prepare a database connection troubleshooting packet准备数据库连接故障排查证据包
Before using the InfiniSynapse DB Compatibility Checker, collect the database engine and version, driver and runtime, sanitized endpoint class, TLS and authentication modes, exact error, first failed layer and a comparison with one known-good path. The checker can organize compatibility questions; it cannot observe your private route, current account state or live listener.使用 InfiniSynapse DB Compatibility Checker 前，应收集数据库引擎与版本、驱动与运行时、脱敏端点类别、TLS 与认证模式、准确错误、首个失败层，并与一条已知正常路径比较。该工具可以整理兼容性问题，但无法观察你的私有路由、当前账户状态或在线监听器。
Review the sanitized compatibility context检查脱敏后的兼容性上下文 Validate every recommendation in the real approved runtime before changing production.任何建议都必须先在真实获准运行时中验证，再用于生产变更。Build a database connectivity evidence packet建立数据库连通性证据包
A useful incident record lets another engineer reproduce the failure without receiving secrets. Capture the following:有效的故障记录应让另一位工程师无需获得密钥即可复现问题。建议收集：
Context环境上下文
UTC timestamp, environment, application version, deployment region, source subnet, runtime, driver and version.UTC 时间、环境、应用版本、部署区域、来源子网、运行时、驱动及版本。
Sanitized target脱敏目标
Database type, masked hostname, port, database or service name, TLS mode, and authentication method—never the secret.数据库类型、脱敏主机名、端口、数据库或服务名、TLS 模式和认证方式，绝不记录密钥本身。
Layer results分层结果
DNS answer, TCP outcome, TLS error, auth result, health query, pool metrics, and exact error code.DNS 结果、TCP 结果、TLS 错误、认证结果、健康查询、连接池指标及准确错误码。
Comparison对比证据
Known-good source, affected source, first failure time, recent network or secret changes, and whether the problem is constant or intermittent.正常来源、受影响来源、首次失败时间、近期网络或密钥变更，以及问题是持续还是间歇发生。
Database Connection Troubleshooting FAQ数据库连接故障排查常见问题
What is database connection troubleshooting?什么是数据库连接故障排查？
It is a layered process for finding the first failure between an application's effective configuration and a usable database operation. The layers normally include DNS, route, TCP, TLS, protocol, authentication, database selection, pooling and a minimal query.它是从应用实际配置到可用数据库操作之间，逐层找出首个失败点的过程。常见层级包括 DNS、路由、TCP、TLS、协议、认证、数据库选择、连接池和最小查询。
What should I check first when a database connection fails?数据库连接失败时应先检查什么？
Start with the exact error, timestamp and failing runtime, then compare its effective host, port, driver and recent changes with a known-good path. Do not reset credentials or open firewall rules until the first failed layer is identified.先记录准确错误、时间和失败运行时，再把其实际主机、端口、驱动与近期变更和已知正常路径比较。在确认首个失败层之前，不要重置凭据或开放防火墙规则。
How do I distinguish a timeout from a refused connection?如何区分连接超时与连接被拒绝？
A timeout means no TCP result arrived within the test window and can involve routing, filtering or an unavailable endpoint. Refused means the destination responded but no listener accepted that address. Preserve the client location and exact endpoint for both.超时表示测试窗口内没有得到 TCP 结果，可能涉及路由、过滤或端点不可用；拒绝连接表示目标已响应，但该地址没有监听器接收。两者都必须保留客户端位置与准确端点。
Why can a port be open while the database connection still fails?为什么端口开放但数据库连接仍会失败？
An open port proves only that a TCP listener accepted the connection. TLS verification, database protocol negotiation, authentication, target database selection, authorization, connection-pool behavior and the first query can still fail afterward.端口开放只能证明 TCP 监听器接受了连接。之后的 TLS 验证、数据库协议协商、认证、目标数据库选择、授权、连接池行为和首个查询仍可能失败。
Why does a database connection work locally but fail in the application?为什么数据库连接在本地正常而应用中失败？
The application may use different DNS, routing, environment variables, secret versions, drivers, trust stores, service identities or pool settings. Reproduce the test inside the same container, VM, host and account instead of assuming a laptop result represents production.应用可能使用不同的 DNS、路由、环境变量、密钥版本、驱动、truststore、服务身份或连接池设置。应在相同容器、虚拟机、主机和账户内复现，而不能假设个人电脑结果代表生产环境。
What evidence is safe to share for a connection failure?连接故障中哪些证据可以安全分享？
Share sanitized engine and driver versions, endpoint class, port, TLS mode, authentication type, exact error, timestamps and stage results. Remove passwords, tokens, private keys, complete production connection strings and sensitive host inventories.可以分享脱敏后的引擎与驱动版本、端点类别、端口、TLS 模式、认证类型、准确错误、时间戳和各阶段结果。必须删除密码、令牌、私钥、完整生产连接字符串和敏感主机清单。