cdata-driver-cli

SKILL：CData Driver CLI

データモデル

ドライバーは、データソースをリレーショナルモデルとして公開します。

• クエリ可能なエンティティを表すテーブル
• テーブルの属性を構成する列
• アクションの実行をサポートするプロシージャ

---

CLI の実行

CLI は cdatacli としてインストールされ、インストール後は PATH に追加されます。

cdatacli <group> <subcommand> [options]

Java 17 以降が必要です。ドライバーは、CLI 実行ファイルからの相対パスである ./ または ./lib/ から検出されます。

シェル構文： 以下の例では bash/zsh の構文を使用しています。Windows PowerShell では、次のように変更してください。

• mkdir -p <dir> → New-Item -ItemType Directory -Force <dir>
• \ による行継続 → バッククォート `
• > file は Windows PowerShell 5.1 では UTF-16 で書き込まれるため、生成された SKILL.md が破損する可能性があります。代わりに | Out-File -Encoding utf8 file を使用してください（PowerShell 7 以降では、すでに UTF-8 で書き込まれます）。
• 接続文字列に $ や、シェルによって展開されるその他の文字が含まれる場合は、シングルクォートで囲んでください。

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 スキルのフロントマターのプレフィックス（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 を一度に 1 つずつ追加してください。
5. 日付フィルターでタイムアウトを防ぐ — 大規模なデータソースでは、フィルターを指定しないクエリがタイムアウトすることがあります。
6. 不可能だと判断する前にプロシージャを確認する — ファイル操作、一括エクスポート、認証フローは、ストアドプロシージャとして提供されていることがよくあります。
7. 列挙型／選択リストのフィールド — フィルターをかける前に、専用テーブル（例：PickListValues）がないか確認してください。値を推測しないでください。

---

推奨ワークフロー

ステップ 1：目標を理解する

先に進む前に、ソースと目標（何を照会するか、または何を達成するか）を確認します。

ソース固有の SKILL が ~/skills/cdata-<source>/ にすでにインストールされている場合は、それを呼び出します。インストールされていない場合は、cdatacli drivers skill <Driver> を試します。内容が返されたら、新しいスキルとして保存し、呼び出します。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 を解決し、--output <dir>（デフォルトは ./lib/）に JAR を書き込みます。この場所は 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 は、ライセンスを登録する人の名前とメールアドレスです。30 日間の試用版には --trial を使用します。購入したキーを使用する場合は、上記の注意に従ってください。

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 を実行する前に、これをユーザーに表示してください。

パスワード、API トークン、その他の秘密情報をこの AI セッションに貼り付けることは推奨されません。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 を追加

OAuth 接続の作成後、最初のクエリを実行するとブラウザーが開き、認証が行われます。以降のクエリではトークンが自動更新されます。

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

接続は暗号化された .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/

---

ステップ 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：クエリを実行する

前のステップで確認した列名のみを使用してください。段階的に組み立ててください。

query sql では、--connection と --sql に加えて、次の 2 つの制限を任意で指定できます。

• --timeout <seconds> — クエリのタイムアウト（デフォルトは 30）。応答の遅いデータソースや大規模なデータソースでは、値を大きくしてください。
• --max-rows <n> — 結果セットごとに返される最大行数（デフォルトは 1000）。結果はこの行数で通知なく打ち切られるため、--max-rows を増やさない限り、大きなテーブルに対する SELECT * では最初の 1000 行のみが返されます。意図的にサンプルを取得するには 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 配列を数えます（上記では、cnt が 368 の行が 1 行です）。バッチの場合は results[].resultset を読み取ります。
• metadata は列（名前、型）を記述するもので、データを記述するものではありません。値を読み取る際は無視してください。
• データソースを問わず、rows キーはありません。SELECT がデータを返さなかったのは、resultset が [] の場合のみです。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