What does ODBC connection mean?ODBC connection 是什么意思？
ODBC connection identifies a specific part of the path applications use to reach ODBC. A successful low-level test proves only that one stage responded. A usable database session also requires correct name resolution, route, the database listener port, the selected ODBC driver and database wire protocol, compatible client software, TLS trust, authentication, database selection and permission for the intended operation.ODBC connection 标识应用程序访问 ODBC 连接路径中的特定组成部分。低层测试成功只证明一个阶段有响应。可用数据库会话还需要正确的名称解析、路由、the database listener port、协议、兼容客户端、TLS 信任、认证、数据库选择以及目标操作权限。
Reproduce the failure through the same application binary, operating-system account and ODBC architecture that production uses. Record whether the application uses a DSN or a DSN-less string, the Driver Manager and driver versions, 32-bit or 64-bit process architecture, sanitized attributes, SQLSTATE, native error and the diagnostic order returned by SQLGetDiagRec.应使用与生产环境相同的应用程序二进制、操作系统账户和 ODBC 架构复现故障。记录应用使用 DSN 还是无 DSN 连接字符串、Driver Manager 与驱动版本、32 位或 64 位进程架构、脱敏属性、SQLSTATE、原生错误码，以及 SQLGetDiagRec 返回的诊断顺序。
Trace an ODBC connection through every component逐层跟踪 ODBC Connection 的组件
ODBC is an API contract, not a database protocol or a single network transport. An application calls an ODBC Driver Manager; the manager locates and loads a vendor driver; the driver interprets connection attributes and speaks the database-specific protocol. A DSN or connection string supplies configuration, while the operating system, process architecture and driver installation determine what is actually visible. This layered design explains why the same credentials can work in one program and fail in another.ODBC 是 API 契约，不是数据库协议，也不是单一网络传输。应用调用 ODBC Driver Manager；Driver Manager 定位并加载供应商驱动；驱动解释连接属性并使用数据库专用协议。DSN 或连接字符串提供配置，而操作系统、进程位数和驱动安装决定应用实际能看到什么。这种分层设计解释了为什么相同凭据可能在一个程序中成功、在另一个程序中失败。
Begin by identifying the exact process that fails: executable path, 32- or 64-bit architecture, service account, working directory and runtime environment. Then capture the Driver Manager, driver name and version, data source type, sanitized effective attributes and final server endpoint. A successful test in the ODBC administrator only proves the administrator process can load that driver and use that configuration; it does not automatically reproduce a Windows service, scheduled task, container or application server.首先识别真正失败的进程：可执行文件路径、32/64 位、服务账户、工作目录和运行环境。然后记录 Driver Manager、驱动名称和版本、数据源类型、脱敏后的实际属性以及最终服务器端点。ODBC 管理器中的测试成功，只能证明该管理器进程能够加载驱动并使用这份配置，并不能自动复现 Windows 服务、计划任务、容器或应用服务器。
| Layer层级 | Failure signal失败信号 | Evidence to collect应收集证据 |
|---|---|---|
| Application应用 | Different behavior between tools using the same DSN name.使用同一 DSN 名称的工具表现不同。 | Process architecture, account, connection API and working environment.进程位数、账户、连接 API 和工作环境。 |
| Driver ManagerDriver Manager | Data source not found or no default driver specified.找不到数据源或未指定默认驱动。 | DSN scope, registry view/config file and installed driver list.DSN 范围、注册表视图/配置文件和已安装驱动列表。 |
| Driver驱动 | Unsupported keyword, protocol negotiation or conversion error.不支持的关键字、协议协商或类型转换错误。 | Driver vendor, exact version, documented attributes and native error.驱动供应商、准确版本、已记录属性和原生错误。 |
| Database path数据库路径 | Timeout, TLS failure, login rejection or operation denial.超时、TLS 失败、登录拒绝或操作被拒。 | Resolved endpoint, transport timing, certificate, identity and server logs.解析端点、传输计时、证书、身份和服务器日志。 |
Choose between a DSN and a driver connection string在 DSN 与驱动连接字符串之间选择
A DSN gives a connection configuration a local name and centralizes selected attributes on that machine. This can simplify desktop administration and allow an operator to update an endpoint without editing every workbook. It also introduces deployment state: the named data source must exist in the correct scope, architecture and host. A driver connection string is more explicit and portable in automated deployment, but only when configuration is managed securely and every required attribute is declared.DSN 为连接配置提供本地名称，并在该机器上集中管理部分属性。它可以简化桌面管理，并允许管理员更新端点而无需编辑每个工作簿，但也引入部署状态：同名数据源必须存在于正确范围、位数和主机中。无 DSN 的驱动连接字符串在自动化部署中更显式、更易移植，但前提是配置得到安全管理，并明确声明全部必要属性。
Do not mix secret storage with configuration portability. Whether using a DSN or a string, keep reusable passwords out of source code, screenshots and broadly readable files. Prefer approved secret injection, integrated identity or short-lived credentials when supported. Record non-secret attributes—driver, server, database, encryption policy, certificate behavior, timeouts and application intent—in version-controlled deployment configuration, then obtain secrets at runtime.不要把密钥存储与配置可移植性混为一谈。无论使用 DSN 还是连接字符串，都不要把可复用密码放入源代码、截图或广泛可读文件。支持时优先使用获准的密钥注入、集成身份或短期凭据。驱动、服务器、数据库、加密策略、证书行为、超时和应用用途等非密钥属性可以进入版本化部署配置，密钥则在运行时获取。
| Decision factor决策因素 | DSNDSN | Driver connection string驱动连接字符串 |
|---|---|---|
| Deployment部署 | Requires a correctly scoped local data-source definition.需要范围正确的本地数据源定义。 | Can travel with managed application configuration.可随受管应用配置一起部署。 |
| Change ownership变更责任 | Often owned by desktop or system administration.通常由桌面或系统管理员负责。 | Often owned by the application deployment pipeline.通常由应用部署流水线负责。 |
| Reproducibility可复现性 | Must export or recreate non-secret settings on every host.必须在每台主机导出或重建非密钥设置。 | Explicit when all relevant keywords are controlled.当所有相关关键字受控时更明确。 |
Diagnose ODBC with SQLSTATE and native errors使用 SQLSTATE 与原生错误诊断 ODBC
ODBC diagnostic records contain more than a message string. The five-character SQLSTATE provides a standardized error class and subclass, while the native error number and message come from the driver or database. A single API call can return multiple diagnostic records, so capture the full ordered chain. Frameworks that retain only the first human-readable sentence can discard the vendor code needed to distinguish authentication, network and server conditions.ODBC 诊断记录不只有一段错误消息。五字符 SQLSTATE 提供标准化错误类别与子类别，原生错误编号和消息则来自驱动或数据库。一次 API 调用可能返回多条诊断记录，因此应保存完整有序链。只保留第一句可读文本的框架可能丢弃用于区分认证、网络和服务器问题的供应商代码。
| SQLSTATE familySQLSTATE 类别 | Meaning to investigate需要调查的含义 | Useful comparison有用比较 |
|---|---|---|
IM classIM 类
|
Driver Manager, DSN, driver loading or function support.Driver Manager、DSN、驱动加载或函数支持。 | Application bitness versus installed driver and DSN scope.应用位数与已安装驱动及 DSN 范围。 |
08 class08 类
|
Connection exception or communication path.连接异常或通信路径。 | Driver native code, endpoint, transport timing and server log.驱动原生代码、端点、传输计时和服务器日志。 |
28 class28 类
|
Invalid authorization specification.无效授权规范。 | Identity class, secret source, authentication mode and account state.身份类别、密钥来源、认证模式和账户状态。 |
42 class42 类
|
Syntax or access-rule problem after connection.连接后的语法或访问规则问题。 | Exact SQL, database context, object name and effective privileges.准确 SQL、数据库上下文、对象名和实际权限。 |
Log diagnostic records with a correlation identifier, timestamp, operation name and sanitized connection context. Never log a full connection string simply because the driver returned it. Separate transient errors that may justify a bounded retry from deterministic configuration errors that will only create more load if retried.记录诊断时应包含关联标识、时间戳、操作名和脱敏连接上下文。不要因为驱动返回完整连接字符串就直接写入日志。应区分可能适合有界重试的瞬时错误，与重试只会增加负载的确定性配置错误。
Build an ODBC compatibility matrix before rollout上线前建立 ODBC 兼容性矩阵
An ODBC upgrade can change TLS defaults, supported authentication, Unicode handling, type mappings, timestamp precision and connection pooling behavior without changing the application’s visible DSN name. Test the combinations that production actually runs: operating system, process architecture, Driver Manager, driver version, database version and authentication method. Include at least one representative query for each important data type and operation class.ODBC 升级可能改变 TLS 默认值、支持的认证、Unicode 处理、类型映射、时间戳精度和连接池行为，即使应用看到的 DSN 名称没有变化。应测试生产真实组合：操作系统、进程位数、Driver Manager、驱动版本、数据库版本和认证方法。每个重要数据类型及操作类别至少包含一项代表性查询。
- Prove driver discovery证明驱动发现Run under the application account and architecture, not only an administrator session.在应用账户和相同位数下运行，而不只是管理员会话。
- Prove secure login证明安全登录Verify encryption, certificate identity and the intended authentication mechanism.验证加密、证书身份和预期认证机制。
- Prove data semantics证明数据语义Compare nulls, Unicode, decimals, dates, binary values and parameter binding.比较 NULL、Unicode、小数、日期、二进制值和参数绑定。
- Prove lifecycle behavior证明生命周期行为Exercise pool reuse, idle timeout, failover, cancellation and clean shutdown.测试连接池复用、空闲超时、故障切换、取消和正常关闭。
Validate ODBC data behavior after connection succeeds连接成功后验证 ODBC 数据行为
Compatibility is incomplete when login succeeds but values change meaning. Build a read-only fixture that covers the data types the application actually uses: Unicode text, null and empty values, high-precision decimals, dates around timezone or daylight-saving boundaries, timestamps with fractional precision, long text, binary data and large identifiers. Retrieve the fixture through the upgraded driver and compare both value and metadata such as type, precision, scale and nullability.登录成功但数据含义发生变化时，兼容性仍不完整。应建立只读测试数据，覆盖应用真实使用的数据类型：Unicode 文本、NULL 与空值、高精度小数、时区或夏令时边界日期、带小数精度的时间戳、长文本、二进制数据和大型标识符。通过升级后的驱动读取测试数据，并同时比较数值和类型、精度、小数位及可空性等元数据。
Exercise parameter binding separately from result retrieval. Drivers can agree on displayed values while differing in how parameters are encoded, rounded or inferred. Test prepared statements, repeated parameters, batch operations and transaction boundaries using non-production data. Record driver and Driver Manager versions, application architecture, locale and connection attributes with the result. If a difference is intentional, document the application adaptation and rollback condition; do not silently accept truncation or implicit conversion warnings.参数绑定应与结果读取分开测试。不同驱动可能显示相同值，却在参数编码、舍入或推断上不同。使用非生产数据测试预处理语句、重复参数、批量操作和事务边界，并随结果记录驱动与 Driver Manager 版本、应用位数、区域设置和连接属性。如果差异是有意的，应记录应用适配与回滚条件，不要静默接受截断或隐式转换警告。
Finally, compare row counts and checksums produced by the old and new path over a small approved fixture. Investigate every mismatch before rollout, including differences caused by locale, encoding or timezone defaults. Preserve the fixture definition and expected results so the same acceptance test can be repeated after future driver, operating-system or database upgrades.最后，在小型获准测试数据上比较新旧路径产生的行数和校验结果。上线前调查每项不一致，包括由区域设置、编码或时区默认值造成的差异。保留测试数据定义和预期结果，使未来驱动、操作系统或数据库升级后可以重复同一验收测试。
A repeatable ODBC connection diagnostic workflow可重复的 ODBC 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 listener port used by the process.验证 DNS 答案、路由、代理以及进程实际使用的 the database 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 password, integrated, Kerberos, certificate or token authentication, database or service selection and effective permissions.验证 driver-supported password, integrated, Kerberos, certificate or token authentication、数据库或服务选择以及有效权限。
- 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 ODBC connection evidence for compatibility review为兼容性审查准备 ODBC connection 证据
Prepare sanitized engine and version, client runtime, driver and version, source environment, endpoint, the database 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 listener port、数据库或服务、TLS 模式、认证方法、有效非密钥属性、准确错误、首个失败阶段和近期变更。不要包含密码、令牌、私钥或未脱敏生产字符串。
Review ODBC connection compatibility审查 ODBC connection 兼容性
Use the InfiniSynapse DB Compatibility Checker to review the target engine against the named ODBC driver, driver architecture, protocol and encryption requirements. Then test the actual DSN or DSN-less configuration from the consuming process, because a generic compatibility result cannot reveal machine-specific registration, service-account visibility or Driver Manager behavior.可使用 InfiniSynapse DB Compatibility Checker 检查目标数据库引擎与指定 ODBC 驱动、驱动架构、协议和加密要求是否匹配。随后必须从实际消费进程测试 DSN 或无 DSN 配置，因为通用兼容性结果无法反映本机驱动注册、服务账户可见性或 Driver Manager 行为。
Open DB Compatibility Checker打开 DB Compatibility CheckerODBC connection FAQODBC connection 常见问题
What is an ODBC connection?什么是 ODBC connection？
An ODBC connection is a session opened when an application calls the ODBC API and the Driver Manager selects a registered driver to use a DSN or connection string. Success depends on matching architecture and attributes as well as the database endpoint.ODBC connection 是应用调用 ODBC API 后，由 Driver Manager 选择已注册驱动，并通过 DSN 或连接字符串建立的会话。能否成功不仅取决于数据库端点，还取决于架构与连接属性是否匹配。
How do I test the same ODBC connection an application uses?如何测试应用实际使用的 ODBC connection？
Test from the same host, user or service account, process architecture and driver as the application. Use the exact DSN or sanitized DSN-less attributes, perform a minimal read-only statement, and capture every SQLSTATE, native error and diagnostic message in order.应使用与应用相同的主机、用户或服务账户、进程架构和驱动进行测试。采用同一 DSN 或脱敏后的无 DSN 属性，执行最小只读语句，并按顺序记录全部 SQLSTATE、原生错误码和诊断消息。
Why can an ODBC connection reach the server but fail authentication?为什么 ODBC 能到达服务器却无法完成认证？
The driver may reach the listener but select the wrong catalog, reject the TLS chain, use an unsupported authentication mode or present credentials from a different service account. Distinguish connection-class SQLSTATEs such as 08xxx from authorization-class 28xxx diagnostics and retain the native code.驱动可能已经到达监听器，但选择了错误目录、拒绝 TLS 证书链、使用了不受支持的认证模式，或由另一个服务账户提交凭据。应区分 08xxx 连接类与 28xxx 授权类 SQLSTATE，并保留原生错误码。
Should an ODBC database endpoint be public?ODBC 数据库端点应该公开到公网吗？
ODBC itself is a client API, not a reason to expose a database listener. Prefer private routing and source rules limited to approved application hosts. If remote users need access, use an approved gateway or private-access service with verified encryption and audited identity.ODBC 本身是客户端 API，不能成为公开数据库监听器的理由。应优先使用私有路由，并把来源规则限制到获准应用主机。若远程用户确需访问，应通过具备加密验证和身份审计的获准网关或私有访问服务。
What ODBC details can I share without exposing secrets?哪些 ODBC 细节可以在不泄露秘密的情况下分享？
Share the Driver Manager and driver versions, process architecture, anonymized DSN scope and name, nonsecret connection attributes, SQLSTATE, native code and message sequence. Remove passwords, access tokens, client-key paths, bearer values and complete production connection strings.可以分享 Driver Manager 与驱动版本、进程架构、匿名化的 DSN 范围和名称、非敏感连接属性、SQLSTATE、原生错误码与消息顺序。必须删除密码、访问令牌、客户端密钥路径、Bearer 值和完整生产连接字符串。
How do I update an ODBC driver or DSN safely?如何安全更新 ODBC 驱动或 DSN？
Install the new driver side by side when supported and create a parallel DSN or configuration name. Test it under the real service identity, canary selected consumers, keep the former driver and DSN for rollback, and remove them only after pooled and scheduled workloads have completed.若支持并行安装，应先安装新驱动并创建新的 DSN 或配置名称。在真实服务身份下测试后，选择部分消费者灰度切换；保留旧驱动和 DSN 作为回滚，待连接池与计划任务均完成后再移除。