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/ から検出されます。

シェル構文： 以下の例では 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 で書き込まれます）。
• 接続文字列に $ や、シェルが展開するその他の文字が含まれる場合は、接続文字列をシングルクォートで囲んでください。
• 接続文字列の引用符： 値に ; などの特殊文字（パスワードなど）が含まれる場合は、外側の --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> と説明）に続いて、ドライバー固有の手順が出力されます。

出力を、ユーザーの AI コーディングツールがスキル（またはルール／手順）を読み込むディレクトリのいずれかに SKILL.md として保存してください。適切な場所はツールと、意図する範囲によって異なります。ユーザーレベル（ユーザーのすべてのプロジェクトで利用可能）か、プロジェクトレベル（単一のプロジェクトとともにコミット）を選べます。固定のパスを想定しないでください。たとえば、次のようになります。

• Claude Code： ~/.claude/skills/cdata-<source>/SKILL.md（ユーザーレベル）または .claude/skills/cdata-<source>/SKILL.md（プロジェクトレベル）
• その他のエージェント（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. JOIN の前にフィルターを適用する — まず WHERE を適用し、JOIN は一度に 1 つずつ追加します。
5. 日付フィルターでタイムアウトを防ぐ — 大規模なデータソースでは、フィルターなしのクエリはタイムアウトします。
6. 不可能だと結論付ける前にプロシージャを確認する — ファイル操作、一括エクスポート、認証フローは、ストアドプロシージャとして提供されていることがよくあります。
7. 列挙型／選択リストのフィールド — フィルターをかける前に、専用テーブル（例：PickListValues）がないか確認します。値を推測しないでください。

---

推奨ワークフロー

ステップ 1：CLI がインストールされていることを確認する

ほかの作業を始める前に、CLI が使用可能であることを確認します。

cdatacli --version

失敗した場合（コマンドが見つからない場合）は、インストールしてから 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：目的を把握する

作業を進める前に、ソースと目的（何をクエリするか、または何を達成するか）を確認します。

ソース固有の SKILL が AI ツールのスキルディレクトリ（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 も含まれます。この値は有効期限が切れると 0 になり、その時点で 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 日間のトライアル期間が終了しており、続けて利用するには購入済みライセンスが必要であることをユーザーに伝えてください。JDBC ドライバーライセンスの購入先として https://www.cdata.com/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 を実行する前に、これをユーザーに表示してください：

パスワード、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 を追加

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

前の手順で確認した列名のみを使用してください。少しずつ組み立ててください。

query sql では、--connection と --sql に加えて、次の任意のフラグを使用できます：

• --timeout <seconds> — クエリのタイムアウト（デフォルトは 30）。処理の遅いデータソースや大規模なデータソースでは値を大きくしてください。
• --max-rows <n> — 返される行数の上限（結果セットごと、デフォルトは 1000）。結果はこの数で警告なく上限処理されます。そのため、より大きなテーブルに対する SELECT * は、--max-rows の値を増やさない限り、最初の 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 配列を数えます（上の例では、cnt が 368 の行が 1 つです）。バッチの場合は、results[].resultset を読み取ります。
• metadata（列名／型）はデフォルトでは省略され、--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 が原因の可能性があります。独断で変更せず、ユーザーにその旨を伝えて、削除するかどうかを確認してください。確認が取れたら、接続を再作成するのではなく、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 を使用してください。