cdata-cli-odbc

技能：CData CLI — ODBC 构建

cdata-cli 技能的构建阶段配套技能。cdata-cli 使用 JDBC 驱动处理发现工作 （连接、探索架构、验证 SQL）；一旦开始编写应用代码并使用 CData ODBC Driver， 就由本技能接手。这是适用于 Node.js 及任何支持 ODBC 的非 JVM 运行时的跨语言方案。

发现阶段验证的所有内容都可以直接沿用：所有 CData 驱动共享相同的关系模型和 SQL 方言， 因此，通过 cdatacli 确认的表名、列名和 SQL，在 ODBC 中也可以原样使用。

---

语言／驱动版本

语言	CData 版本	ODBC 绑定
Node.js / JS / TS	CData ODBC Driver	odbc（npm）
PHP	CData ODBC Driver	PDO_ODBC（PHP 捆绑扩展）
C / C++	CData ODBC Driver	原生 ODBC API（sql.h、sqlext.h）
Go	CData ODBC Driver	database/sql + 社区 ODBC 驱动包
Ruby	CData ODBC Driver	社区 ODBC gem
Rust	CData ODBC Driver	社区 ODBC crate

ODBC 驱动属于 CData；让语言能够调用 ODBC 的绑定则属于该语言自身的生态系统， 并非由 CData 发布。有些绑定实际上已成为标准方案（Node 的 odbc、PHP 的 PDO_ODBC、C/C++ ODBC API）；其他语言（Go、Ruby、Rust）则依赖社区包，因为 Go 的 database/sql 等只提供通用数据库接口，并未内置 ODBC 实现。请确认目标语言当前 受维护的绑定，不要想当然地假定某个特定包可用。下文仅展示 Node odbc 路径的具体示例代码。

ODBC 是跨语言备用方案。如果某种语言有一等 CData 版本，应优先使用该版本—— Python → cdata-cli-python、.NET → cdata-cli-adonet；对于没有专用版本的语言 （Node.js、Go、PHP、Ruby、C/C++、Rust），或明确要求使用 ODBC 时，再选用 ODBC。

---

前提条件：先完成发现

如果本次会话尚未使用 cdata-cli，请停止并先调用它。 本技能仅涵盖构建阶段—— 在继续之前，必须通过 cdata-cli 完成连接设置、架构发现和 SQL 验证。

本技能假设已使用 cdata-cli 确认源可以连接，并验证应用将要运行的确切表、列和 SQL。 请在此处复用这些结果。如果发现阶段创建的 cdatacli 连接通过浏览器完成了 OAuth 登录，请记下其 OAuthSettingsLocation——应用的 DSN／连接字符串可以指向同一缓存令牌文件， 从而跳过重新认证（参见配置连接）。

在运行时，CLI 只能直接使用 Java/JDBC。 它无法安装或激活 ODBC Driver，也无法为其 创建连接——这些正是本技能要处理的内容。ODBC Driver 是单独的运行时驱动版本，作为系统 驱动安装；CLI 不负责获取或管理它。

---

步骤 1：确认已安装 ODBC Driver

与 JDBC jar（maven）或 ADO.NET 提供程序（NuGet）不同，ODBC 驱动是安装在系统中的驱动， 需在操作系统 ODBC Driver Manager 中注册。它不会从软件包仓库获取，而是通过 CData ODBC 安装包（Windows 上为安装程序／.msi；Linux/macOS 上为发行版软件包）安装；cdatacli 不负责安装它。

检查驱动是否已存在：

# Windows
Get-OdbcDriver | Where-Object Name -like "*CData*"
# e.g. "CData ODBC Driver for Salesforce"  (note the 32-bit / 64-bit rows)

# Linux/macOS (unixODBC)
odbcinst -q -d        # list registered driver names

已安装的驱动 DLL/so 通常位于以下位置（Windows 示例）：

C:\Program Files\CData\CData ODBC Driver for <Source>\lib64\CData.ODBC.<Source>.dll   # 64-bit

位数必须匹配。 应用进程、ODBC Driver Manager 和驱动必须采用相同的体系结构。64 位 Node/Go/PHP 进程需要 64 位 CData ODBC 驱动，并且 DSN 必须创建在 64 位注册表配置单元中。 混用 32/64 位是最常见的 ODBC 故障（参见故障排除）。

如果尚未安装驱动，用户必须先为该数据源安装 CData ODBC 驱动（从其 CData 下载内容中获取）， 然后再次检查。

---

Step 2: 许可证

cdatacli 连接成功并不意味着此驱动已激活。 cdatacli 使用 JDBC 驱动，因此只能证明 JDBC 已获得许可——ODBC 驱动需要单独的许可证。

CData ODBC 驱动的许可证在安装时应用（安装向导 / CData 许可证工具会应用试用密钥或产品密钥），并且许可证按计算机授权，与 JDBC/ADO.NET/Python 版本分开。在驱动已安装并获得许可的计算机上，无需进一步操作。

如果查询因许可证错误而失败，用户应通过安装程序 / CData 许可证工具重新激活 ODBC 驱动（产品密钥属于机密——请在 AI 编码会话之外完成此操作）。激活方式取决于安装程序和平台，因此请遵循 CData ODBC 驱动自身的设置流程，而不要在此编写脚本步骤。

---

Step 3: 配置连接

首先，检查此数据源是否已有 DSN——如果有，请向用户确认是否复用：

# Windows — list all User and System DSNs
Get-OdbcDsn | Where-Object Name -like "*<Source>*"
# or list everything: Get-OdbcDsn

# Linux/macOS
odbcinst -q -s    # list all registered DSN names

如果存在合适的 DSN，请跳至 Step 4，并使用 DSN=<name> 连接。否则，请按下面的说明进行设置。

有两种连接方式——DSN（命名的已存储配置）或 DSN-less（代码中的完整连接字符串）。无论采用哪种方式，都应复用发现过程中验证过的属性；对于 OAuth 数据源，将 OAuthSettingsLocation 指向发现过程中的令牌缓存，以免在 DSN / 字符串中保存机密，也不会触发浏览器流程。

Option A — DSN（推荐复用）

用户 DSN 无需管理员权限，作用范围仅限当前用户；系统 DSN 对整台计算机生效，需要管理员权限。创建用户 DSN，并复用缓存的 OAuth 令牌：

# Windows — creates a 64-bit User DSN (no secrets stored: token comes from the cache file)
Add-OdbcDsn -Name "MySource SBX" -DriverName "CData ODBC Driver for <Source>" `
  -DsnType User -Platform "64-bit" -SetPropertyValue @(
    "AuthScheme=OAuth",
    "InitiateOAuth=GETANDREFRESH",
    "OAuthSettingsLocation=C:\...\CData\<Source> Data Provider\OAuthSettings-xxx.txt"
  )

# Linux/macOS (unixODBC): register the driver in odbcinst.ini, then a DSN in odbc.ini
# ~/.odbc.ini
[MySource SBX]
Driver = CData ODBC Driver for <Source>
AuthScheme = OAuth
InitiateOAuth = GETANDREFRESH
OAuthSettingsLocation = /home/you/.cdata/OAuthSettings-xxx.txt

只需使用名称连接：DSN=MySource SBX。

Option B — DSN-less（自包含）

在连接字符串中填写驱动程序名称和所有属性——无需预先注册：

Driver={CData ODBC Driver for <Source>};AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;OAuthSettingsLocation=C:\...\OAuthSettings-xxx.txt

Driver={...} 的值必须与 Step 1 中的驱动程序名称完全一致。

**机密信息：**内置 OAuth 的数据源（例如 Salesforce）只需要缓存的令牌。 不包含内置 OAuth 应用的来源（例如 Gmail）需要用户自己的 OAuthClientId/OAuthClientSecret，即使只是刷新令牌也需要——请在运行时通过环境 变量提供这些值，切勿将其写入已提交到代码库的 DSN 或字符串中。

---

Step 4: 从代码连接

Node.js（odbc）

npm install odbc 会安装预构建二进制文件——在常见平台上无需 C/C++ 编译器。

import odbc from "odbc";

// DSN or DSN-less connection string both work:
const CS = process.env.SF_ODBC_DSN || "DSN=MySource SBX";

const pool = await odbc.pool(CS);           // pool for a server app
const rows = await pool.query(
  "SELECT Id, Name FROM Account WHERE Name LIKE ?", ["%Acme%"]);   // ? placeholders
console.log(rows.length, rows[0]?.Name);

• ? 占位符（qmark），通过数组传递值——始终使用参数化方式处理输入。
• 读取时使用 pool.query；INSERT/UPDATE/DELETE 也使用相同方式。对于短期单次连接，请使用 odbc.connect(CS)。

其他语言

在所有支持 ODBC 的语言中，连接模式都相同：使用 DSN=<name>（或不使用 DSN 的 Driver={...} 字符串）连接，使用 ? 参数标记执行 SQL，并遍历结果。使用目标语言自身的 ODBC 绑定（见上表），并使用通过 cdatacli 验证过的相同 SQL。

---

Step 5: 端到端示例（Node.js）

一个最小化的仓库代码示例（可根据需要封装在 Express/Fastify 等框架中）：

import odbc from "odbc";

const CS = process.env.SF_ODBC_DSN || "DSN=MySource SBX";
let poolPromise = null;
const getPool = () => (poolPromise ??= odbc.pool(CS));

export async function listAccounts(search, limit = 50) {
  const pool = await getPool();
  let sql = "SELECT Id, Name FROM Account";
  const params = [];
  if (search) { sql += " WHERE Name LIKE ?"; params.push(`%${search}%`); }
  sql += ` ORDER BY Name LIMIT ${Number(limit)}`;
  return pool.query(sql, params);
}

export async function createAccount(name, industry = null) {
  const pool = await getPool();
  return pool.query("INSERT INTO Account (Name, Industry) VALUES (?, ?)", [name, industry]);
}

---

故障排查

症状	原因 / 解决方法
Data source name not found and no default driver specified / architecture mismatch	位数不匹配，或 DSN 注册在错误的注册表配置单元中。确保应用进程、Driver Manager 和驱动程序均为 64 位（或均为 32 位），并且 DSN 存在于对应的配置单元中。
找不到驱动程序名称（无 DSN）	Driver={...} 名称与已安装的驱动程序不匹配。请使用 Get-OdbcDriver / odbcinst -q -d 返回的确切名称。
查询时出现许可证错误	此计算机上的 ODBC 驱动程序尚未获得许可——请在 AI 会话之外，通过 CData ODBC 安装程序 / 许可证工具（步骤 2）重新激活。
'OAuthClientId' and 'OAuthClientSecret' are needed to initiate OAuth	源中没有嵌入式 OAuth 应用；请将客户端 ID / 密钥（来自环境变量）添加到 DSN / 连接字符串中，并确保与缓存了刷新令牌的应用匹配。
npm install odbc 尝试编译 / 失败	通常会使用预构建二进制文件；如果触发编译，请确保使用受支持的 Node 版本和平台，或安装构建工具以进行备用原生构建。