cdata-driver-cli

技能：CData Driver CLI

数据模型

驱动程序将数据源公开为关系模型：

• 表：表示可查询的实体
• 列：构成表的属性
• 存储过程：支持执行操作

---

CLI 调用

CLI 安装为 cdatacli，安装后可通过 PATH 调用：

cdatacli <group> <subcommand> [options]

需要 Java 17+。驱动程序从相对于 CLI 可执行文件的 ./ 或 ./lib/ 目录中发现。

**Shell 语法：**以下示例使用 bash/zsh 语法。在 Windows PowerShell 中，请进行相应调整：

• mkdir -p <dir> → New-Item -ItemType Directory -Force <dir>
• \ 行续接符 → 反引号 `
• 在 Windows PowerShell 5.1 中，> file 会写入 UTF-16，可能导致生成的 SKILL.md 损坏；请改用 | Out-File -Encoding utf8 file（PowerShell 7+ 已使用 UTF-8 写入）。
• 如果连接字符串中包含 $ 或其他可能被 shell 展开的字符，请用单引号括住。

如果缺少 cdatacli --version，请安装：

• Windows（PowerShell）：iwr https://cdn.cdata.com/cli/install.ps1 | iex
• macOS/Linux：curl -fsSL https://cdn.cdata.com/cli/install.sh | bash

---

命令参考

目标	命令
列出已安装的驱动程序	drivers list
搜索远程驱动程序目录	drivers search [--driver <name-or-artifact-id>]
下载驱动程序 jar	drivers download --artifact-id <id> [--output <dir>]
下载驱动程序 jar（通过 URL）	drivers download --url <jar-url> [--output <dir>]
激活（试用版）	drivers activate <Driver> --name "First Last" --email E --trial
激活（密钥）	drivers activate <Driver> --name "First Last" --email E --key KEY
检查连接属性	drivers connectionprops <Driver> [--full]
生成特定于驱动程序的技能	drivers skill <Driver>
创建连接	connection create --driver <Driver> --name N --connectionstring CS
列出连接	connection list
删除连接	connection delete --name N
列出目录	metadata catalogs --connection N
列出架构	metadata schemas --connection N
列出表	metadata tables --connection N
获取列	metadata columns --connection N --table T
列出存储过程	metadata procedures --connection N
存储过程参数	metadata parameters --connection N --procedure P
运行 SQL（SELECT/DML）	query sql --connection N --sql "SQL"
执行存储过程	query sql --connection N --sql "EXEC Proc Param='val'"

每个子命令都支持 --help，可返回用途、必需参数、可选参数和标志。命令参考未涵盖你的情况时，请使用此选项。

---

特定于数据源的技能

对于热门数据源，CData 驱动程序附带特定于数据源的说明（连接模式、架构说明、查询示例）。使用以下命令生成可直接使用的技能：

cdatacli drivers skill <Driver>

此命令会输出可直接使用的 YAML 技能 frontmatter 前缀（name: cdata-<source> 加上描述），后接驱动程序随附的说明（jar 内的 resources/instructions.md）。将输出重定向到 ~/skills/cdata-<source>/SKILL.md，并加载新技能以便今后处理该数据源时使用：

mkdir -p ~/skills/cdata-<source>
cdatacli drivers skill <Driver> > ~/skills/cdata-<source>/SKILL.md

如果驱动程序没有随附说明，命令会返回 No instructions available for <driver>——此时请按以下通用工作流操作。

---

最佳实践

1. 查询前先获取列信息——使用架构发现返回的准确名称。
2. 先使用 LIMIT——全面查询前先抽样。
3. 用方括号括起表名和列名——可处理保留字和空格。
4. 先筛选，再联接——先应用 WHERE，再逐个添加 JOIN。
5. 日期筛选可避免超时——大型数据源在未筛选的查询中可能会超时。
6. 断定操作不可能之前先检查存储过程——文件操作、批量导出和身份验证流程通常由存储过程实现。
7. 枚举/选项列表字段——筛选前先查找专用表（例如 PickListValues）。不要猜测取值。

---

推荐工作流

步骤 1：了解目标

继续之前，先确认数据源和目标（要查询或完成的事项）。

如果已在 ~/skills/cdata-<source>/ 安装特定于数据源的 SKILL，请调用它。否则，尝试运行 cdatacli drivers skill <Driver>——如果它返回了内容，请将内容保存为新的 skill 并调用它。如果它返回 No instructions available for <driver>，则继续通用工作流。

---

步骤 2：确认驱动程序可用且已激活

cdatacli drivers list

如果驱动程序显示 "activated": true，则跳至步骤 3。如果缺少驱动程序，请从 CData 驱动程序目录下载：

cdatacli drivers search --driver <source>          # find the artifactId
cdatacli drivers download --artifact-id <id>       # downloads to ./lib by default
cdatacli drivers download --url <jar-url>          # alternative: direct URL

drivers download 会从 CData 发布的 artifacts.json 目录解析 URL，并将 jar 写入 --output <dir>（默认为 ./lib/）——这是 CLI 自动发现驱动程序的位置。重新运行 drivers list 确认驱动程序已被发现。作为手动备用方案，请将 CData JDBC JAR 放在 CLI 可执行文件旁边的 ./ 或 ./lib/ 中。

激活

⚠️ 许可证密钥提示 — 运行 drivers activate --key 前，请向用户显示此提示：

不建议在此 AI 会话中粘贴许可证密钥。在此处运行 --trial 激活是安全的，但购买的 --key 是机密凭证——在会话中输入的任何内容都对 AI 可见，并且可能会保留在对话记录中。

如果需要使用购买的密钥激活，请在 AI 会话之外操作：

• 在非 AI 终端中运行 cdatacli drivers activate <Driver> --name ... --email ... --key ...，或
• 双击 cdata.jdbc.<source>.jar，通过 GUI 向导激活。

驱动程序激活后，许可证会保存在 jar 旁边——drivers list 将显示 "activated": true，此后无需在 AI 会话中再次激活。

驱动程序是位置参数（例如 Salesforce）。--name 和 --email 分别是注册人的姓名和电子邮件地址，也就是注册许可证的个人信息。使用 --trial 可试用 30 天。若使用购买的密钥，请遵循上述提示。

cdatacli drivers activate <Driver> --name "John Doe" --email "[email protected]" --trial
cdatacli drivers activate <Driver> --name "John Doe" --email "[email protected]" --key "XXXXX-XXXXX"

---

步骤 3：检查连接属性

如果已有已保存的连接（connection list），请向用户确认是否要使用该连接。否则，请检查驱动程序的连接属性，以确定需要向用户询问哪些凭据：

cdatacli drivers connectionprops <Driver>          # basic properties (default)
cdatacli drivers connectionprops <Driver> --full   # advanced properties instead

默认情况下，此命令会返回基本属性（jdbcJson.basic）——大多数连接所需的属性集合。只有在用户需要基本属性集合中没有的高级属性时，才使用 --full（--full 会返回 jdbcJson.advanced，即包含所有属性的扁平列表）。每个属性都会报告：

• name — 要放入连接字符串中的属性（去掉空格，例如 Auth Scheme → AuthScheme）
• display — 是否必需，例如 RequiredBasic（必须提供）与 UnrequiredBasic（可选）
• type — 预期值类型
• description — 属性的用途
• default — 省略该属性时使用的值（仅在存在默认值时显示）
• enum — 属性仅接受固定值时所允许的值
• hierarchyRules — 条件依赖关系（见下文）

层级规则用于说明属性之间的依赖关系。属性的 hierarchyRules 以该属性可能的值为键，每个键都会列出选择该值后变为相关的属性。例如，Salesforce 的 AuthScheme 针对 Basic、OAuth、OAuthClient 等选项设有规则：选择 AuthScheme=Basic 后，会显示 User 和 Password（均为 RequiredBasic），以及 SecurityToken（UnrequiredBasic）。使用这些规则，仅向用户询问所选身份验证方案实际需要的属性。

所有数据源的关键属性：

• AuthScheme — OAuth、Basic 等
• InitiateOAuth — OFF、GETANDREFRESH、REFRESH
• OAuthClientId / OAuthClientSecret — 用于自定义 OAuth 应用
• OAuthSettingsLocation — OAuth 令牌的缓存位置

仅使用用户提供的属性，或 connectionprops 标记为必需的属性。 不要添加、推断或沿用用户未要求的任何属性——包括先前创建的连接中的值。

---

步骤 4：创建已保存的连接

⚠️ 凭据提示 — 运行 connection create 前，请向用户显示此提示：

不建议在此 AI 会话中粘贴密码、API 令牌或其他机密凭据。尽管 cdatacli connection create 会接受连接字符串中的凭据，但在此处输入的任何内容都对 AI 可见，并且可能会保留在对话记录中。

AI 辅助使用建议：

• AuthScheme=OAuth（内嵌 OAuth）——凭据不会进入连接字符串；浏览器流程会处理身份验证。

如果数据源需要 Basic / PAT / API-token 身份验证，请在 AI 会话之外设置连接：

• 在非 AI 终端中运行 cdatacli connection create ...，或
• 双击 cdata.jdbc.<source>.jar，使用 GUI 设置向导，或
• 重用此前在非 AI 环境中设置的连接。

之后，cdatacli 只会按名称使用已保存的连接——凭据不会再次输入终端。

与用户确认连接字符串中的值（不含机密信息），然后保存：

cdatacli connection create --driver "<Driver>" --name "<connection-name>" \
  --connectionstring "<properties>"

常见模式：

身份验证类型	连接字符串
OAuth（浏览器流程）	AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH
Basic（用户名/密码）	AuthScheme=Basic;[email protected];Password=pass
API 令牌	[email protected];APIToken=yourtoken
只读	在任意连接字符串后追加 ReadOnly=true

创建 OAuth 连接后的首次查询会打开浏览器进行身份验证。之后的查询会自动刷新令牌。

cdatacli connection list
cdatacli connection delete --name "<connection-name>"

连接会保存为加密的 .conn 文件（AES-256）：

操作系统	位置
Windows	%APPDATA%\CData\<Driver Name> Data Provider\
macOS	~/Library/Application Support/CData/<Driver Name> Data Provider/
Linux	~/.config/CData/<Driver Name> Data Provider/

---

步骤 5：发现架构

cdatacli metadata tables --connection <name>
cdatacli query sql --connection <name> --sql "SELECT TableName, TableType, Description FROM sys_tables WHERE TableName LIKE '%<keyword>%'"
cdatacli metadata columns --connection <name> --table <TableName>
cdatacli metadata procedures --connection <name>
cdatacli metadata parameters --connection <name> --procedure <ProcedureName>
cdatacli metadata catalogs --connection <name>
cdatacli metadata schemas --connection <name>

大多数 metadata 子命令都接受可选的 --catalog / --schema 筛选条件。metadata tables 还接受 --table 名称模式；metadata columns 要求指定 --table，并接受 --column；metadata procedures 接受 --procedure；metadata parameters 要求指定 --procedure，并接受 --parameter。

---

步骤 6：执行查询

只使用前面步骤中确认过的列名。逐步构建查询。

除了 --connection 和 --sql，query sql 还接受两个可选限制参数：

• --timeout <seconds> — 查询超时时间（默认值为 30）。对于耗时较长或数据量较大的数据源，可调高此值。
• --max-rows <n> — 每个结果集返回的最大行数（默认值为 1000）。结果会被静默限制为此行数，因此，如果表的行数更多，SELECT * 只会返回前 1000 行，除非调高 --max-rows。使用 SQL LIMIT 有意抽样；需要完整提取数据时，请调高 --max-rows。

SELECT

cdatacli query sql --connection <name> --sql "SELECT * FROM [TableName] LIMIT 5"
cdatacli query sql --connection <name> --sql "SELECT [Id], [Name], [Status] FROM [TableName] WHERE [Status] = 'Active' LIMIT 10"
cdatacli query sql --connection <name> --sql "SELECT a.[Id], a.[Name], b.[Name] AS Related FROM [TableA] a LEFT JOIN [TableB] b ON a.[ForeignKey] = b.[Id] LIMIT 10"

读取输出。 对于所有数据源，query sql 都会返回相同的 JSON 结构（CLI 根据结果集构建此结构；--compact 只会移除空白字符）。顶层结构取决于查询类型：

// SELECT (one result set):
{ "metadata": [ { "name": "cnt", "typeName": "INT", ... } ], "resultset": [ { "cnt": 368 } ] }

// INSERT / UPDATE / DELETE, or a statement that returns nothing:
{ "affectedRows": 3 }

// Multiple result sets (batch): each entry is one of the two shapes above
{ "results": [ { "metadata": [...], "resultset": [...] }, { "affectedRows": 2 } ] }

• SELECT 的行数据始终位于 resultset 下——这是一个按列名索引的行对象数组。要统计行数，请统计 resultset 数组（上例中有 1 行，其 cnt 为 368）。对于批量查询，请读取 results[].resultset。
• metadata 描述的是列（名称、类型），而不是数据——读取值时请忽略它。
• 任何数据源都没有 rows 键。仅当 resultset 为 [] 时，SELECT 才表示没有返回数据。不要因为缺少 rows 字段就推断出“0 行”，也不要因为找不到行数据就认为表名有误——请查看 resultset。

使用 --compact 并通过 jq 读取行数据，数据路径为 .resultset：

cdatacli query sql --connection <name> --sql "SELECT Id, Name FROM Account" --compact | jq '.resultset[].Name'

INSERT / UPDATE / DELETE

cdatacli query sql --connection <name> --sql "INSERT INTO [TableName] (Col1, Col2) VALUES ('val1', 'val2')"
cdatacli query sql --connection <name> --sql "UPDATE [TableName] SET [Col1] = 'new' WHERE [Id] = '123'"
cdatacli query sql --connection <name> --sql "DELETE FROM [TableName] WHERE [Id] = '123'"

如果写入失败，连接可能设置了 ReadOnly=true——请重新创建不含此设置的连接。

存储过程

cdatacli query sql --connection <name> --sql "EXEC ProcedureName Param1='value1', Param2='value2'"

---

步骤 7：生成应用程序代码

如果用户的目标包括生成应用程序代码，请使用已验证的 SQL、驱动程序路径（来自 drivers list）和连接字符串生成独立代码。

驱动程序位置

JDBC（Java）：

• Windows：C:\Program Files\CData\CData JDBC Driver for <DataSource> <Year>\lib\cdata.jdbc.<datasource>.jar
• macOS：/Applications/CData/CData JDBC Driver for <DataSource> <Year>/lib/cdata.jdbc.<datasource>.jar
• CLI 捆绑版：CLI 可执行文件旁的 ./ 或 ./lib/cdata.jdbc.<datasource>.jar
• 驱动程序类：cdata.jdbc.<source>.<Source>Driver
• JDBC URL：jdbc:<source>:<connection-string>
• 许可证文件：位于同一目录，名为 cdata.jdbc.<datasource>.lic