PolarDB-X Glue 数据源 (Data Source)
XDataSource
类 (Class) 在 PolarDB-X Glue 中充当符合 JDBC (Java Database Connectivity) 规范的连接工厂 (connection factory)。它实现了标准的 javax.sql.DataSource
接口 (interface)，同时利用增强的 RPC (Remote Procedure Call) 后端 (backend) 进行连接管理 (connection management) 和性能监控 (performance monitoring)。此组件 (component) 是应用程序通过 PolarDB-X Glue 层获取数据库连接的入口点 (entry point)。
概述 (Overview)
XDataSource
为连接到 PolarDB-X 数据库实例 (database instances) 提供了一个 JDBC 兼容的接口 (interface)。它封装了连接参数 (connection parameters)、超时配置 (timeout configurations) 和性能监控，同时将实际的连接管理委托给 XConnectionManager
单例 (singleton)。该数据源维护着查询性能 (query performance)、缓存利用率 (cache utilization) 和故障切换操作 (switchover operations) 的统计信息 (statistics)。
XDataSource 集成架构 (XDataSource Integration Architecture)
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
39-83
配置管理 (Configuration Management)
XDataSource
管理连接参数 (connection parameters) 和配置设置 (configuration settings)，这些参数和设置将应用于此数据源创建的所有连接。配置内容包括数据库连接详细信息、超时设置 (timeout settings) 和编码偏好 (encoding preferences)。
连接参数 (Connection Parameters)
数据源存储了在构造期间传入的关键连接信息：
host | ||
port | ||
username | ||
password | ||
defaultDatabase | ||
name |
数据源初始化流程 (Data Source Initialization Flow)
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
70-83
超时配置 (Timeout Configuration)
数据源提供了可配置的超时设置，这些设置会影响连接获取 (connection acquisition) 和查询执行 (query execution)：
连接超时 (Connection Timeout) ： getConnTimeoutNanos
控制从连接池 (pool) 获取连接时的等待时间。查询超时 (Query Timeout) ： defaultQueryTimeoutNanos
设置 SQL (Structured Query Language) 操作的默认 socket 超时时间。
这些超时可以通过相应的 setter 方法以纳秒 (nanoseconds) 和毫秒 (milliseconds) 为单位进行配置。
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
48-126
编码配置 (Encoding Configuration)
defaultEncodingMySQL
参数允许设置数据库连接的字符编码 (character encoding)。该实现会自动将 utf8
转换为 utf8mb4
，以兼容 MySQL 的扩展 UTF-8 支持。
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
113-118
连接创建 (Connection Creation)
XDataSource
的主要功能是通过 getConnection()
方法创建 XConnection
实例 (instances)。此过程涉及与 XConnectionManager
协调并应用数据源特定的配置 (configurations)。
连接创建序列 (Connection Creation Sequence)
连接创建过程包括错误处理 (error handling)，以确保如果配置失败，连接能得到正确的清理 (cleaned up)。
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
198-222
性能监控集成 (Performance Monitoring Integration)
XDataSource
通过原子计数器 (atomic counters) 维护全面的性能统计信息 (performance statistics)，并集成到故障切换监控系统 (switchover monitoring system) 中，以应对故障转移场景 (failover scenarios)。
性能计数器 (Performance Counters)
该数据源跟踪各种性能指标 (metrics)：
queryCount | |
updateCount | |
tsoCount | TSO |
totalRespondTime | |
totalPhysicalTime |
缓存性能跟踪 (Cache Performance Tracking)
与缓存相关的指标监控查询计划 (query plan) 和 SQL 缓存的有效性：
cachePlanQuery | |
cacheSqlQuery | |
cachePlanMiss | |
cacheSqlMiss | SQL |
故障切换监控 (Switchover Monitoring)
该数据源与 SwitchoverPerfCollection
集成，用于跟踪数据库故障转移 (failover events) 期间的性能。此集合是在初始化期间，根据从数据源名称中提取的实例信息，从 XConnectionManager
获取的。
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
52-68src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
164-166
状态与诊断 (Status and Diagnostics)
XDataSource
提供了用于监控底层连接池 (connection pool) 健康状况和状态的方法：
状态信息 (Status Information)
getStatus()
: 返回当前的XClientPool.XStatus
，指示连接池的健康状况。getDigest()
: 提供连接配置的唯一标识符 (unique identifier)。getUrl()
: 生成 X 协议 (X protocol) 格式的连接 URL (Uniform Resource Locator) 字符串。
URL 生成 (URL Generation)
getUrl()
方法构造了一个连接字符串，其中包括：
协议标识符 ( X://
) (Protocol identifier)认证信息 (Authentication information) 连接参数 (超时、编码、查询超时) (Connection parameters)
此 URL 格式遵循以下模式：
X://username@host:port/database?connectTimeout=value&characterEncoding=value&socketTimeout=value
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
168-196
JDBC 兼容性 (JDBC Compliance)
XDataSource
实现了标准的 JDBCDataSource
接口 (interface)，但有一些限制：
支持的操作 (Supported Operations)
getConnection()
: 创建新的数据库连接getConnection(String, String)
: 委托给无参数版本unwrap()
和isWrapperFor()
: 标准的包装器模式 (wrapper pattern) 支持
不支持的操作 (Unsupported Operations)
几个 JDBC 方法会抛出 NotSupportException
：
getLogWriter()
和setLogWriter()getLoginTimeout()
和setLoginTimeout()getParentLogger()
来源:src/main/java/com/alibaba/polardbx/rpc/compatible/XDataSource.java
224-266
附录1: 用户应该如何通过 PolarDB-X Glue 特有的机制，来配置和监控连接池的连接获取超时（即替代 getLoginTimeout()
的功能）？
如何在 PolarDB-X Glue 中配置和监控连接池的连接获取超时，以替代标准 JDBC 的 getLoginTimeout()
功能。
配置连接获取超时
PolarDB-X Glue 通过 XDataSource
类提供了专门的连接获取超时配置机制:
1. 使用 getConnTimeoutNanos
属性
XDataSource
提供了 getConnTimeoutNanos
字段来控制连接获取超时, 默认值为 XConfig.DEFAULT_GET_CONN_TIMEOUT_NANOS
(5秒)。
2. 配置方法
您可以通过以下方法设置超时时间:
纳秒级别: setGetConnTimeoutNanos(long nanos)毫秒级别: setGetConnTimeoutMillis(long millis)
3. 超时机制的实现
当调用 XDataSource.getConnection()
时,该超时值会传递给底层的连接池.
在 XClientPool.getConnection()
方法中,超时检查会在连接获取循环中执行.
如果超时,会抛出 ERR_X_PROTOCOL_CONNECTION
错误。
监控连接获取状态
PolarDB-X Glue 提供了多种监控机制:
1. 等待连接数监控
通过 perfCollection.getGetConnectionCount()
可以获取当前正在等待连接的请求数.
2. 诊断信息
使用 XClientPool.diagnose()
方法可以获取详细的连接池状态,包括等待连接数.
3. 状态查询
通过 XDataSource.getStatus()
可以获取连接池的整体状态.
与标准 JDBC 的区别
需要注意的是,XDataSource
的 getLoginTimeout()
和 setLoginTimeout()
方法目前抛出 NotSupportException
, PolarDB-X Glue 使用了自己的超时机制.
Notes
连接获取超时是在 XDataSource
层面配置的,而不是通过标准 JDBC 的setLoginTimeout()
方法超时值支持纳秒级精度,提供了更细粒度的控制 系统还会检查并发连接数和等待连接数是否超过阈值 ( XprotoMaxDnConcurrent
和XprotoMaxDnWaitConnection
),超过时会直接拒绝连接请求连接获取过程包括多个阶段:从空闲会话池获取、创建新会话、创建新TCP连接等,每个阶段都会检查剩余超时时间
附录2: 由于 getLogWriter()
不受支持，我们应该如何获取 XDataSource
或底层 XConnectionManager
的内部运行日志？PolarDB-X Glue 是否提供了推荐的、非标准的日志框架或配置接口来替代标准的 JDBC 日志功能？
如何获取 XDataSource
或 XConnectionManager
的内部运行日志，因为标准 JDBC 的 getLogWriter()
方法不受支持。
PolarDB-X Glue 的日志框架
PolarDB-X Glue 使用自定义的日志框架 XLog
，而不是标准 JDBC 的 LogWriter
机制。
核心日志组件
系统提供了多个专门的日志记录器：
XLog.XLogLogger
- 通用运行日志，记录连接池管理、会话创建/销毁等核心事件XLog.XProtocolLogger
- 协议级别的调试日志，记录 SQL 执行历史XLog.XRequestLogger
- 请求日志，记录慢查询和请求详情XLog.XPerfLogger
- 性能日志，定期输出性能指标
日志输出示例
系统会自动记录关键事件：
数据源初始化/销毁：记录连接池的创建和引用计数
连接池健康检查：定期输出检查耗时
TCP 连接异常：记录坏连接的移除
错误和异常：所有异常都会通过
XLog.XLogLogger.error()
记录
性能监控接口
除了日志，系统还提供了编程式的性能监控接口：
1. DN 级别性能数据
通过 XConnectionManager.gatherDnPerf()
收集数据库节点的性能指标.
2. TCP 连接性能数据
通过 XConnectionManager.gatherTcpPerf()
收集 TCP 连接的性能指标.
3. 会话性能数据
通过 XConnectionManager.gatherSessionPerf()
收集会话级别的性能指标.
4. 数据源级别的计数器
XDataSource
提供了多个原子计数器用于监控
queryCount
/updateCount
- 查询和更新次数totalRespondTime
/totalPhysicalTime
- 响应时间统计cachePlanQuery
/cacheSqlQuery
- 缓存命中统计
日志配置
PolarDB-X Glue 使用 LoggerFactory
创建日志记录器，这通常基于 SLF4J 或类似的日志框架。 您需要在应用的日志配置文件（如 logback.xml
或 log4j2.xml
）中配置相应的日志级别：
<!-- 示例配置 -->
<logger name="com.alibaba.polardbx.rpc" level="INFO"/>
<logger name="XLog.XLogLogger" level="INFO"/>
<logger name="XLog.XProtocolLogger" level="DEBUG"/>
<logger name="XLog.XRequestLogger" level="INFO"/>
<logger name="XLog.XPerfLogger" level="INFO"/>
与标准 JDBC 的区别
XDataSource.getLogWriter()
和 setLogWriter()
方法抛出 NotSupportException
，因为系统使用了自己的日志框架而不是标准 JDBC 的 PrintWriter
机制。
Notes
PolarDB-X Glue 的日志系统是完全自定义的，不依赖标准 JDBC 的 LogWriter
接口日志记录器通过 LoggerFactory
创建，支持标准的 Java 日志框架（SLF4J/Logback/Log4j2）性能监控数据可以通过编程方式定期收集，系统也会自动通过 XPerfLogger
定期输出 JSON 格式的性能数据事务泄漏检查功能（ enableTrxLeakCheck
）会记录详细的堆栈跟踪信息，帮助诊断问题慢查询日志会在 XResult.doLog()
中自动记录，阈值由XConnectionManager.getSlowThresholdNanos()
控制
