What does JDBC connection mean?JDBC connection 是什么意思？
JDBC connection identifies a specific part of the path applications use to reach JDBC. A successful low-level test proves only that one stage responded. A usable database session also requires correct name resolution, route, the database-specific listener port, the database vendor protocol implemented by the JDBC driver, compatible client software, TLS trust, authentication, database selection and permission for the intended operation.JDBC connection 标识应用程序访问 JDBC 连接路径中的特定组成部分。低层测试成功只证明一个阶段有响应。可用数据库会话还需要正确的名称解析、路由、the database-specific listener port、协议、兼容客户端、TLS 信任、认证、数据库选择以及目标操作权限。
Start with the JVM process that fails, because its class path, JDBC driver, truststore, DNS view and connection-pool settings may differ from a developer shell. Capture the sanitized JDBC URL shape, driver artifact and version, JDK version, SQLState, vendor error code and the first SQLException in the chain; keep credentials and private key material out of logs and tickets.应从真正失败的 JVM 进程开始排查，因为它的 classpath、JDBC 驱动、truststore、DNS 视图和连接池设置可能与开发终端不同。记录脱敏后的 JDBC URL 结构、驱动构件与版本、JDK 版本、SQLState、厂商错误码以及异常链中的首个 SQLException；不要把凭据或私钥材料写入日志和工单。
Trace a JDBC connection from JVM to database从 JVM 到数据库跟踪 JDBC Connection
JDBC defines Java interfaces for database access; the selected driver implements those interfaces and the database wire protocol. A connection therefore depends on the JVM, application class path or module path, driver artifact and version, JDBC URL, properties, DNS and network path, TLS trust material, authentication method and database target. A generic “connection failed” message can originate before any network packet is sent or after a fully established database session.JDBC 定义 Java 数据库访问接口，所选驱动负责实现这些接口以及数据库线协议。因此，连接依赖 JVM、应用 classpath 或 module path、驱动包及版本、JDBC URL、属性、DNS 与网络路径、TLS 信任材料、认证方式和数据库目标。通用的“连接失败”可能发生在尚未发送任何网络数据之前，也可能发生在数据库会话已经建立之后。
Capture evidence from the deployed Java process. A command-line
test can use a different JDK, trust store, DNS configuration and
driver JAR than the application server. Record the Java runtime
vendor/version, effective class path, loaded driver class and
artifact version, sanitized URL, non-secret properties, pool
implementation and the complete chained
SQLException. When a framework wraps the exception,
retain the root cause and every next exception before changing
configuration.证据应来自实际部署的 Java
进程。命令行测试可能使用与应用服务器不同的 JDK、信任库、DNS
配置和驱动 JAR。应记录 Java 运行时供应商/版本、实际
classpath、已加载驱动类与包版本、脱敏
URL、非密钥属性、连接池实现以及完整的链式
SQLException。框架包装异常时，应在修改配置之前保留根因和所有后续异常。
| JDBC layerJDBC 层级 | Typical signal典型信号 | Next evidence下一步证据 |
|---|---|---|
| Driver discovery驱动发现 | No suitable driver or class-loading failure.没有合适驱动或类加载失败。 | Runtime class path, module configuration, driver service registration and artifact version.运行时 classpath、模块配置、驱动服务注册和包版本。 |
| URL parsingURL 解析 | Driver rejects the URL or silently applies an unexpected default.驱动拒绝 URL 或静默应用非预期默认值。 | Vendor URL grammar, property precedence and resolved database target.供应商 URL 语法、属性优先级和解析后的数据库目标。 |
| Transport and TLS传输与 TLS | Timeout, refused socket or certificate-path error.超时、套接字拒绝或证书路径错误。 | Resolved address, connect timeout, active trust store and certificate identity.解析地址、连接超时、实际信任库和证书身份。 |
| Database session数据库会话 | SQLState, vendor code, login rejection or wrong database context.SQLState、供应商代码、登录拒绝或错误数据库上下文。 | Chained exception, authentication mode, selected schema/catalog and server log.异常链、认证模式、所选 schema/catalog 和服务器日志。 |
Treat the JDBC URL as vendor-specific configuration把 JDBC URL 视为供应商专用配置
All JDBC URLs begin with jdbc:, but the remaining
syntax belongs to the driver vendor. Host lists, instance or
service names, database selection, encryption, failover and
property delimiters differ across PostgreSQL, MySQL, SQL Server
and Oracle drivers. Copying a URL pattern from another driver
can produce an immediate parse error—or a more dangerous
connection to an unintended default database. Validate the URL
against documentation for the exact driver version.所有 JDBC URL 都以
jdbc:
开头，但后续语法由驱动供应商定义。PostgreSQL、MySQL、SQL Server
和 Oracle
驱动在主机列表、实例或服务名、数据库选择、加密、故障切换和属性分隔符方面都不同。复制另一驱动的
URL
模式可能立即解析失败，也可能更危险地连接到非预期默认数据库。必须针对准确驱动版本的文档验证
URL。
Define property precedence so operators know whether a value in
the URL, a Properties object, framework
configuration or environment variable wins. Avoid declaring the
same security property in multiple places. At startup, log a
redacted configuration summary that includes driver, endpoint
class, database, TLS policy and timeout values but omits
usernames when sensitive, passwords, tokens and private-key
locations. This makes configuration drift observable without
exposing secrets.应定义属性优先级，使运维人员知道 URL、Properties
对象、框架配置或环境变量中的哪个值最终生效。避免在多个位置重复声明同一安全属性。启动时记录脱敏配置摘要，包括驱动、端点类别、数据库、TLS
策略和超时，但省略敏感用户名、密码、令牌和私钥位置，从而在不泄露密钥的情况下观察配置漂移。
Compatibility rule: an accepted URL proves only that this driver parsed it. Verify the connected product/version and database identity with a bounded read-only query before running migrations or writes.兼容性规则：URL 被接受只能证明该驱动完成了解析。执行迁移或写入前，应通过有界只读查询验证实际连接的产品、版本和数据库身份。
Design JDBC pool and timeout behavior together统一设计 JDBC 连接池与超时行为
A production JDBC call may wait in several different places: DNS resolution, socket connection, TLS handshake, authentication, pool acquisition, statement execution and network read. One large application-level timeout hides which budget was consumed. Configure bounded timeouts at the layers supported by the driver and pool, then report them separately. The pool acquisition timeout should reflect how long a request may wait for a reusable connection; it is not a substitute for a network connect timeout.生产 JDBC 调用可能在多个位置等待：DNS 解析、套接字连接、TLS 握手、认证、连接池获取、语句执行和网络读取。单一的大应用超时会掩盖真正消耗预算的阶段。应在驱动和连接池支持的层级分别设置有界超时并单独报告。连接池获取超时表示请求等待可复用连接的时长，不能替代网络连接超时。
Size pools from workload concurrency and database capacity rather than multiplying a default by the number of application instances. A pool of 20 across 50 pods can create 1,000 possible sessions before operational or failover demand is counted. Define maximum pool size, minimum idle behavior, connection lifetime, idle timeout, leak detection and validation strategy as one capacity model. Add jitter to retirement so every instance does not replace connections simultaneously.连接池大小应基于工作负载并发和数据库容量，而不是把默认值乘以应用实例数。50 个 Pod 每个连接池上限为 20，在考虑运维或故障切换需求之前就可能产生 1,000 个会话。应把连接池上限、最小空闲、连接生命周期、空闲超时、泄漏检测和验证策略作为统一容量模型，并对连接淘汰增加抖动，避免所有实例同时更换连接。
| Test测试 | What it reveals揭示内容 | Required observation必须观察 |
|---|---|---|
| Pool saturation连接池饱和 | Whether callers fail within budget instead of waiting indefinitely.调用方是否在预算内失败，而不是无限等待。 | Acquisition latency, waiting threads and timeout class.获取延迟、等待线程和超时类别。 |
| Database restart数据库重启 | How stale pooled connections are detected and replaced.如何发现并替换池中失效连接。 | Retry volume, recovery time and absence of a reconnect storm.重试量、恢复时间以及是否避免重连风暴。 |
| Certificate rotation证书轮换 | Whether new handshakes use the updated trust material.新握手是否使用更新后的信任材料。 | Fresh and reused connection behavior before and after rotation.轮换前后新连接与复用连接的行为。 |
Preserve the complete SQLException chain保留完整 SQLException 链
SQLException exposes a SQLState, vendor error
code, cause and optional chain of next exceptions. The SQLState
class can distinguish connection exceptions from authorization,
syntax and transaction conditions, while the vendor code
supplies product-specific precision. Log the ordered diagnostic
chain with a correlation ID and operation phase. Do not flatten
everything into HTTP 500 or “JDBC error,” and never include a
URL containing a password.SQLException 提供
SQLState、供应商错误码、原因以及可选的后续异常链。SQLState
类别可区分连接、授权、语法和事务条件，供应商代码则提供产品专用精度。应使用关联
ID 和操作阶段记录有序诊断链，不要把所有问题压平成 HTTP 500
或“JDBC 错误”，也不要记录包含密码的 URL。
Retry only when the error class and operation semantics permit it. A transient connection interruption before a read may be retryable; an authentication rejection, malformed URL or missing driver is deterministic until configuration changes. A transaction whose commit outcome is unknown requires reconciliation before replay, especially for non-idempotent writes. Define retry count, backoff, jitter and total deadline centrally so driver, pool and framework retries do not multiply one another.只有错误类别与操作语义允许时才重试。读取前发生的瞬时连接中断可能适合重试；认证拒绝、URL 格式错误或缺少驱动则在配置变化前都是确定性错误。提交结果未知的事务在重放前必须先核对，尤其是非幂等写入。应集中定义重试次数、退避、抖动和总截止时间，避免驱动、连接池与框架重试相互叠加。
- Classify分类Use SQLState class, vendor code and operation phase.使用 SQLState 类别、供应商代码和操作阶段。
- Preserve context保留上下文Record runtime, driver, sanitized target, pool state and elapsed time.记录运行时、驱动、脱敏目标、连接池状态和耗时。
- Choose a safe action选择安全动作Retry, fail fast, refresh configuration or reconcile the transaction according to evidence.根据证据选择重试、快速失败、刷新配置或核对事务。
Accept a JDBC driver upgrade with behavior tests通过行为测试验收 JDBC 驱动升级
A driver upgrade should be evaluated as an application dependency change, not a file replacement. Review release notes between the deployed and target versions for minimum Java level, removed properties, TLS defaults, authentication support, failover behavior and type-mapping changes. Build the target artifact through the normal dependency process so the test includes shading, module rules and transitive conflicts. At runtime, confirm which driver class and implementation version the JVM actually loaded.驱动升级应视为应用依赖变更，而不是替换文件。检查当前版本到目标版本之间的发布说明，关注最低 Java 版本、已删除属性、TLS 默认值、认证支持、故障切换行为和类型映射变化。通过正常依赖流程构建目标包，使测试覆盖 shading、模块规则和传递依赖冲突；运行时确认 JVM 实际加载的驱动类及实现版本。
The canary suite should open fresh and pooled connections, validate server identity, bind representative parameter types, read metadata, commit and roll back controlled transactions, cancel a bounded query and recover after a planned database interruption. Compare latency and error classification with the baseline rather than requiring byte-for-byte log equality. Record unsupported scenarios and an explicit rollback trigger. Remove the old driver only after every deployment unit has restarted and runtime evidence confirms the target version is loaded.灰度套件应新建及复用连接、验证服务器身份、绑定代表性参数类型、读取元数据、提交并回滚受控事务、取消有界查询，并在计划数据库中断后恢复。应与基线比较延迟和错误分类，而不是要求日志逐字节完全一致。记录未支持场景和明确回滚触发条件。只有所有部署单元都重启且运行时证据确认加载目标版本后，才能删除旧驱动。
A repeatable JDBC connection diagnostic workflow可重复的 JDBC connection 诊断流程
Move from observed runtime context to the first failing stage, then validate the smallest safe correction.从实际运行上下文定位首个失败阶段，再验证最小安全修正。
- Capture the exact context捕获准确上下文Record time, runtime identity, source network, driver/version, sanitized configuration, endpoint, database and error.记录时间、运行身份、来源网络、驱动/版本、脱敏配置、端点、数据库和错误。
- Resolve the effective destination解析实际目标Verify DNS answers, route, proxy and the exact the database-specific listener port used by the process.验证 DNS 答案、路由、代理以及进程实际使用的 the database-specific listener port。
- Test transport and TLS测试传输与 TLSMeasure socket and handshake stages separately; verify trust chain and server identity.分别测量套接字与握手阶段，验证信任链和服务器身份。
- Test identity and target scope测试身份与目标范围Validate driver-supported credentials, integrated identity, Kerberos, certificates, IAM or tokens, database or service selection and effective permissions.验证 driver-supported credentials, integrated identity, Kerberos, certificates, IAM or tokens、数据库或服务选择以及有效权限。
- Run a minimal safe operation运行最小安全操作Use a deterministic, bounded, read-only operation before representative workload testing.先运行确定性、有界、只读操作，再进行代表性工作负载测试。
- Correct, retest and monitor修正、重测与监控Change one controlled variable, preserve rollback, retest from the failing context and watch recurrence.一次只改变一个受控变量，保留回滚，从失败上下文重测并观察复发。
Prepare JDBC connection evidence for compatibility review为兼容性审查准备 JDBC connection 证据
Prepare sanitized engine and version, client runtime, driver and version, source environment, endpoint, the database-specific listener port, database or service, TLS mode, authentication method, effective non-secret properties, exact error, first failing stage and recent changes. Never include passwords, tokens, private keys or unredacted production strings.准备脱敏后的引擎与版本、客户端运行时、驱动与版本、来源环境、端点、the database-specific listener port、数据库或服务、TLS 模式、认证方法、有效非密钥属性、准确错误、首个失败阶段和近期变更。不要包含密码、令牌、私钥或未脱敏生产字符串。
Review JDBC connection compatibility审查 JDBC connection 兼容性
Use the InfiniSynapse DB Compatibility Checker to compare the database engine with the exact JDBC driver, Java runtime, URL format and TLS expectations you plan to deploy. Its review can expose questions about driver support or connection properties, but the release decision still requires an application-level test through the real DataSource or pool under approved credentials.可使用 InfiniSynapse DB Compatibility Checker 对照计划部署的数据库引擎、具体 JDBC 驱动、Java 运行时、URL 格式和 TLS 要求。检查结果可以暴露驱动支持或连接属性方面的问题，但发布决策仍需在获准凭据下，通过真实 DataSource 或连接池完成应用级验证。
Open DB Compatibility Checker打开 DB Compatibility CheckerJDBC connection FAQJDBC connection 常见问题
What is a JDBC connection?什么是 JDBC connection？
A JDBC connection is a Java SQL session created by a JDBC driver from a database URL and connection properties, commonly through DriverManager or a DataSource. It proves that the driver returned a Connection object; transaction behavior, permissions and application queries still require separate validation.JDBC connection 是 JDBC 驱动根据数据库 URL 和连接属性创建的 Java SQL 会话，通常由 DriverManager 或 DataSource 提供。它只能证明驱动返回了 Connection 对象；事务行为、权限和应用查询仍需单独验证。
How do I test a JDBC connection from an application?如何从应用中测试 JDBC connection？
Run a minimal connection and read-only query from the same JDK, class path, container and DataSource configuration as the failing service. Record the SQLException chain, SQLState and vendor code. A separate TCP port test is useful only as a transport precheck.应在与故障服务相同的 JDK、classpath、容器和 DataSource 配置中建立最小连接并执行只读查询，同时记录 SQLException 异常链、SQLState 和厂商错误码。单独的 TCP 端口测试只能作为传输层预检。
Why can JDBC reach the server but still fail to log in?为什么 JDBC 能到达服务器却仍然登录失败？
The JDBC URL may select the wrong database or service, the driver may negotiate an unsupported authentication method, the JVM may reject the certificate chain, or the account may be invalid. Inspect the first SQLException and its chained causes instead of reducing every failure to a password problem.JDBC URL 可能选错数据库或服务，驱动可能协商了服务端不支持的认证方式，JVM 可能拒绝证书链，账户也可能无效。应查看首个 SQLException 及其后续异常，而不是把所有失败都归因于密码。
Should a JDBC database endpoint be exposed to the internet?JDBC 数据库端点应该暴露到公网吗？
Normally no. Keep the database endpoint on a private network and limit access to application runtimes or an approved access proxy. When an external path is unavoidable, require certificate and host-name verification, strong identity, narrow source rules, monitoring and an explicit risk decision.通常不应。数据库端点应位于私有网络，只允许应用运行时或获准的访问代理连接。若确实无法避免外部路径，应要求证书与主机名验证、强身份认证、严格来源规则、监控以及明确的风险决策。
What JDBC evidence is safe to share for troubleshooting?排查 JDBC 时哪些证据可以安全分享？
Share a JDBC URL with hosts and database names anonymized and all secret-bearing properties removed, plus the driver artifact, driver and JDK versions, pool type, SQLState and vendor error code. Never share passwords, tokens, client private keys, truststore passwords or a complete production URL.可以分享已匿名化主机和数据库名称、并删除所有含密属性的 JDBC URL，以及驱动构件、驱动与 JDK 版本、连接池类型、SQLState 和厂商错误码。切勿分享密码、令牌、客户端私钥、truststore 密码或完整生产 URL。
How do I change a JDBC driver or endpoint without an outage?如何在不中断服务的情况下更换 JDBC 驱动或端点？
Create a parallel DataSource or pool, test it with the target JDK and workload, then canary a small share of instances. Keep the old driver or endpoint available until old pooled connections have drained, monitor error and latency changes, and preserve a configuration rollback.先创建并行 DataSource 或连接池，使用目标 JDK 和工作负载完成测试，再让少量实例灰度切换。旧连接池排空前保留原驱动或端点，同时监控错误率与延迟变化，并保留配置回滚路径。