cdata-cli

技能：CData CLI

数据模型

驱动程序以关系模型的形式公开数据源：

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

---

Java 原生基础

CData CLI 原生基于 Java，并运行于 CData JDBC Driver 之上。此技能中的所有连接管理、架构发现和 SQL 执行，底层都使用 JDBC。

如果目标应用使用 Java 或其他 JVM 语言（Kotlin、Scala），CLI 已设置好的 JDBC jar 和许可证可以直接用于你的应用，无需额外安装驱动程序。如果尚未决定目标语言，这是最简单且推荐的起点。

对于 其他语言——Python、C#/.NET、Node.js、Go 等——CData 会发布单独的运行时驱动程序版本（Python Connectors、ADO.NET Data Providers、ODBC Drivers）。这些驱动程序需要单独下载、安装和获取许可证，CLI 无法完成这些操作。构建技能会引导你完成设置，但与 Java 路径相比，步骤会更多。

---

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 展开的字符，请用单引号括起连接字符串。
• 连接字符串引号： 当值包含 ; 或其他特殊字符（例如密码）时，请用双引号括起外层 --connectionstring，并用单引号括起每个内部值——这样在 PowerShell 7 和 CMD 中都不会被改动： --connectionstring "AuthScheme=Basic;User=me;Password='p;w=d';Other='MaxThreads=10'"

如果找不到 cdatacli --version，请进行安装：

• Windows（PowerShell）：irm https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-windows.ps1 | iex
• macOS：curl -fsSL https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-macos.sh | bash
• Linux：curl -fsSL https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-linux.sh | bash

---

命令参考

目标	命令
接受 EULA（首次运行时必须执行）	license [-y]
列出已安装的驱动程序	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 update --name N --connectionstring CS
更新连接（替换）	connection update --name N --connectionstring CS --replace
更新并跳过验证	connection update --name N --connectionstring CS --force
移除属性	connection update --name N --unset "Key1,Key2"
列出连接	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" [--metadata]
执行存储过程	query sql --connection N --sql "EXEC Proc Param='val'"

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

---

特定于数据源的技能

对于热门数据源，CData 驱动程序会提供特定于数据源的说明（连接模式、架构说明、查询示例）。必须先安装驱动程序——此命令会读取驱动程序 jar 中附带的说明。安装后，使用以下命令生成可直接使用的技能：

cdatacli drivers skill <Driver>

此命令会输出可直接使用的 YAML 技能前置内容（name: cdata-<source> 加上描述），后面接着驱动程序的特定于数据源的说明。

将输出保存为 SKILL.md，存放在用户的 AI 编码工具加载技能（或规则/说明）的目录中——正确位置取决于所用工具和预期范围：用户级（适用于用户的所有项目）或项目级（随单个项目提交）。不要假设路径固定。例如：

• Claude Code： ~/.claude/skills/cdata-<source>/SKILL.md（用户级）或 .claude/skills/cdata-<source>/SKILL.md（项目级）
• 其他 Agent（Cursor、GitHub Copilot、Gemini CLI、Codex 等）：使用相应工具自己的技能/规则/说明目录和文件约定

如果不确定当前工具从哪里加载技能，请先询问用户，再写入文件。然后加载新技能，以便今后处理该数据源。示例（将 <skills-dir> 替换为工具对应的正确位置）：

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

如果驱动程序没有已提交的说明，此命令会返回 No instructions available for <driver>——此时请使用下面的通用工作流。

---

最佳实践

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

---

推荐工作流

步骤 1：确保已安装 CLI

先确认 CLI 可用：

cdatacli --version

如果失败（提示找不到命令），请安装 CLI，然后重新检查 cdatacli --version：

• Windows（PowerShell）：irm https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-windows.ps1 | iex
• macOS：curl -fsSL https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-macos.sh | bash
• Linux：curl -fsSL https://downloads.cdata.com/cdatabuilds/builds/free/cdatacli/install-cdatacli-linux.sh | bash

CLI 需要 Java 17+。

首次运行时的 EULA： 首次使用时，CLI 要求接受 CData 最终用户许可协议 — 在接受之前，命令会因许可协议错误而退出。如果遇到该消息，请运行一次：

cdatacli license -y

这会接受 https://www.cdata.com/company/legal/eula/ 上的 EULA；接受状态按机器保存，因此之后运行命令时不会再次提示。

---

步骤 2：了解目标

继续操作前，确认数据源和目标（要查询或完成的任务）。

如果 AI 工具的技能目录中已安装特定数据源的 SKILL（cdata-<source>），请调用它。否则，暂时不要生成技能 — cdatacli drivers skill <Driver> 会读取驱动程序 jar 中附带的说明，因此只有在驱动程序安装后才能使用。等确认驱动程序已安装（步骤 3）后，再运行 cdatacli drivers skill <Driver>：如果它返回内容，请将其保存为新技能，放在适合用户所用 AI 工具的位置（参见上文“特定数据源的技能”），然后调用它；如果它返回 No instructions available for <driver>，请继续使用通用工作流。

---

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

cdatacli drivers list

drivers list 的输出包含 licenseType（Trial，或已购买许可证的人类可读类型，例如 Enterprise/Developer/Server），且仅对试用许可证包含 trialDaysLeft（过期后会归零，此时 active 会变为 false）。

如果驱动程序显示 "activated": true，请检查 licenseType：

• Trial 且 trialDaysLeft 较少（例如 ≤ 7）或为 0： 告知用户剩余天数（或试用已过期），并引导其前往 https://www.cdata.com/jdbc 购买后再继续 — 不要默默地直接继续。
• 否则，跳到步骤 4。

如果找不到驱动程序，请从 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 会话中再次激活。

激活前先询问——不要默认使用试用版。 先询问用户是否有已购买的许可证密钥，或者是否想申请 30 天试用版。只有在用户确认没有密钥（或明确选择试用版）时，才运行 --trial；如果用户有密钥，请遵循上述许可证密钥提示，不要在此会话中激活。

驱动程序是一个位置参数（例如 Salesforce）。--name 和 --email 是注册人的姓名和电子邮件地址，即注册许可证的个人信息。--trial 用于申请 30 天试用版；--key 用于激活已购买的许可证。

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

如果驱动程序显示试用版已过期（trialDaysLeft: 0、active: false），请告知用户 30 天试用期已结束，继续使用需要购买许可证。引导用户前往 https://www.cdata.com/jdbc 购买 JDBC 驱动程序许可证，然后遵循上述许可证密钥提示，在 AI 会话之外使用密钥激活。

激活试用版后（或之后每次检查 drivers list 时），请向用户报告 trialDaysLeft，以免他们对试用版到期感到意外——提醒他们试用期有限，并且可以随时前往 https://www.cdata.com/jdbc 购买许可证，在试用期结束前转换为正式许可证。

---

第 4 步：检查连接属性

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

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

默认情况下，connectionprops 会返回基本属性，即大多数连接所需的属性集。创建连接前，请让用户确认连接字符串。如果用户需要基本属性集中未包含的高级属性，请在 connectionprops 命令中添加 --full。

未经告知用户，不要将之前连接或会话的连接设置沿用到新连接中。

层级规则说明属性之间的依赖关系。某个属性的 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 令牌的缓存位置

---

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

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

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

AI 辅助使用的推荐方式：

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

如果数据源要求使用 Basic / PAT / API 令牌身份验证，请在 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

cdatacli connection list
cdatacli connection update --name "<connection-name>" --connectionstring "<new-or-changed-properties>"
cdatacli connection update --name "<connection-name>" --connectionstring "<properties>" --replace
cdatacli connection update --name "<connection-name>" --unset "Key1,Key2"
cdatacli connection delete --name "<connection-name>"

默认情况下，connection update 会将新属性合并到现有连接中，适合在不重新创建连接的情况下更改单个属性。使用 --replace 替换整个连接字符串，或使用 --unset 移除指定属性。属性名称不区分大小写。--replace 和 --unset 不能同时使用。使用 --force 可跳过连接验证，适用于占位连接或不连接实时数据源的测试。

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

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

---

步骤 6：发现架构

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。

名称模式使用 % 作为通配符，且不区分大小写。单独的值表示精确匹配——--table Order 只返回 Order，不会返回 OrderItem；使用 --table "%Order%" 可匹配子字符串。_ 按字面字符处理（不是通配符），因此 --column "%__c" 可匹配 Salesforce 自定义字段。包含 % 的模式必须加引号。

---

步骤 7：执行查询

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

除 --connection 和 --sql 外，query sql 还接受以下可选标志：

• --timeout <seconds> — 查询超时时间（默认值为 30）。对于运行缓慢或数据量较大的数据源，请调高此值。
• --max-rows <n> — 每个结果集返回的最大行数（默认值为 1000）。结果会静默截断至此行数，因此，除非调高 --max-rows，否则对较大表执行 SELECT * 只会返回前 1000 行。使用 SQL LIMIT 有意抽样；需要完整提取时，请调高 --max-rows。
• --metadata — 在输出中包含列架构（名称、类型）。默认不包含；仅在需要列类型信息时添加此标志。

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 结构（--compact 只会移除空白）。默认情况下，输出仅包含数据。顶层结构取决于查询类型：

// SELECT (one result set) — default:
{ "resultset": [ { "cnt": 368 } ] }

// SELECT with --metadata — adds a column-schema array:
{ "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 shapes above
{ "results": [ { "resultset": [...] }, { "affectedRows": 2 } ] }

• SELECT 的行数据始终位于 resultset 下——这是一个以列名为键的行对象数组。要统计行数，请统计 resultset 数组中的元素（上例中有 1 行，cnt 为 368）。对于批处理，请读取 results[].resultset。
• 默认情况下会省略 metadata（列名/类型），只有传入 --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。不要自行更改——请告知用户这一点，并询问他们是否希望移除该设置。如果用户确认，请使用 connection update --unset "ReadOnly"，而不是重新创建连接。

存储过程

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

---

第 8 步：生成应用程序代码

步骤 1–7（连接、发现架构、验证 SQL）与语言无关，属于此技能的工作范围。一旦目标从探索数据转为编写应用程序代码，就应移交给适用于目标驱动技术的专用构建技能。

如果尚未确定目标语言，请优先建议 Java。 CLI 已设置好的 JDBC jar 和许可证正是应用程序所需的内容——无需单独安装驱动，也无需额外的许可证步骤。这是从发现数据到构建可运行应用程序最快的路径。其他语言（Python、Node.js、C#、Go 等）也都完全支持，但每种语言都需要单独下载并安装运行时驱动，以及激活许可证，而 CLI 无法执行这些操作——请说明这一权衡，帮助用户做出明智的选择。

如果上下文已经明确目标语言（例如现有代码库、文件，或用户已说明语言），则跳过建议，直接使用匹配的构建技能。

按语言／驱动技术选择构建技能：

使用…构建	调用技能	驱动技术
Java / JVM（也包括 Kotlin、Scala）——推荐	cdata-cli-java	JDBC Driver（CLI 已设置）
Python	cdata-cli-python	CData Python Connector（需单独安装）
C# / .NET（也包括 VB.NET、F#）	cdata-cli-adonet	ADO.NET Data Provider（需单独安装）
Node.js / JavaScript / TypeScript，或任何非 JVM 语言（Go、PHP、Ruby、Rust、C/C++）	cdata-cli-odbc	ODBC Driver（需单独进行系统级安装）

编写代码之前，请调用匹配的构建技能。对于其他技能未涵盖的任何环境，请将 cdata-cli-odbc 作为跨语言备用方案。