sqlclientinfoexception 是 jdbc 4.0 引入的受检异常，用于标识 setclientinfo() 设置客户端元数据失败，常见于驱动不支持、非法键值、连接无效或权限不足等场景。
sqlclientinfoexception 是 java 中 jdbc 4.0 引入的受检异常，当尝试通过 connection.setclientinfo() 设置客户端连接属性（如应用名、用户备注、程序版本等）失败时抛出。它不表示 sql 执行错误，而是客户端元数据配置环节的问题。
常见触发场景与原因
该异常通常由以下情况引发：
- 数据库驱动不支持 client info：例如旧版 MySQL Connector/J（5.1.x 之前）、某些嵌入式或轻量级驱动未实现此特性
-
设置了非法键名或值：如使用未在
DatabaseMetaData.getClientInfoProperties()中声明的 key；value 为空字符串、null 或超长（超出驱动限制，常见上限为 128–256 字符） -
连接已关闭或处于无效状态：调用
setClientInfo()前连接被显式关闭，或底层网络中断导致逻辑连接失效 - 权限不足：部分数据库（如 PostgreSQL 配合特定安全策略）可能限制客户端信息写入，尤其涉及 session-level 参数时
如何安全设置 client info（推荐做法）
避免硬抛异常，应结合元数据检查与异常捕获：
- 调用前先获取支持的属性列表：
DatabaseMetaData meta = conn.getMetaData(); List<clientinfoproperty> props = meta.getClientInfoProperties();</clientinfoproperty>，确认目标 key 是否存在且 value 长度合规 - 使用带 Map 的重载方法一次性设置多个属性：
conn.setClientInfo(Map<string string>)</string>，减少重复调用开销，也便于统一处理失败项 - 对
SQLClientInfoException单独捕获并记录警告，而非中断主流程：“设置 client info 失败，继续执行”——多数业务场景中，该信息仅用于审计或监控，非功能必需 - 生产环境建议禁用非必要 client info（如开发用的 “appVersion=dev-2024”），减少驱动兼容性风险
典型数据库适配说明
不同数据库对 client info 的支持程度差异较大：
-
PostgreSQL（pgjdbc）：从 42.2.0+ 版本起完整支持，key 如
ApplicationName、ClientHostname会映射到pg_stat_activity表对应字段 -
MySQL（MySQL Connector/J）：8.0+ 驱动支持
applicationName（对应program_name），但需开启useInformationSchema=true才能被getClientInfoProperties()返回 -
Oracle（ojdbc8）：支持
ApplicationName、ModuleName等，但要求连接未启用implicit caching，否则 setClientInfo 可能静默失败 - HSQLDB / H2：仅基础支持，常将 client info 存于内存，重启即丢失，适合测试环境
调试与日志建议
定位问题时可启用驱动级日志：
- MySQL：添加 JVM 参数
-Dorg.slf4j.simpleLogger.defaultLogLevel=debug并引入 slf4j-simple，查看是否打印 “ClientInfo not supported” 类提示 - PostgreSQL：设置
loggerLevel=DEBUG和loggerFile=pgjdbc.log，搜索 “clientInfo” 关键字 - 通用方式：在 catch 块中打印异常的
getFailedProperties()返回值，明确哪些 key 设置失败及对应原因码（getSQLState()和getErrorCode()）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
