cdata-cli-odbc

SKILL：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 の database/sql などは、組み込みの ODBC 実装を持たない汎用データベースインターフェイスのみを提供するため、Go、Ruby、Rust ではコミュニティ製パッケージに依存します。特定のパッケージを前提とせず、対象言語で現在も保守されているバインディングを確認してください。以下に具体的なコード例を示すのは、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 を呼び出してください。 このスキルが対象とするのはビルドフェーズのみです。ここに進む前に、cdata-cli を使用して接続の設定、スキーマの検出、SQL の検証を行う必要があります。

このスキルでは、アプリが実行するソースへの接続と、正確なテーブル、列、SQL の検証に、すでに cdata-cli を使用していることを前提としています。ここでは、その結果を再利用してください。検出時に OAuth のブラウザーサインインを行った cdatacli 接続を作成した場合は、その OAuthSettingsLocation を確認してください。アプリの DSN／接続文字列から同じキャッシュ済みトークンファイルを参照すれば、再認証を省略できます（「接続の構成」を参照）。

ランタイムに関して、CLI が直接対応するのは Java/JDBC のみです。 ODBC Driver のインストール、有効化、接続の作成はできません。それらを扱うのがこのスキルです。ODBC Driver は、システムドライバーとしてインストールする別個のランタイムドライバーエディションです。CLI は、その取得や管理には関与しません。

---

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

JDBC jar（maven）や ADO.NET プロバイダー（NuGet）とは異なり、ODBC ドライバーは、OS の 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 ドライバーと、64 ビットのレジストリハイブに作成された DSN が必要です。32 ビット版と 64 ビット版の混在は、ODBC で最もよくある失敗の原因です（「トラブルシューティング」を参照）。

ドライバーがインストールされていない場合は、まずユーザーがソース用の CData ODBC ドライバーを（CData からダウンロードして）インストールしてから、再確認する必要があります。

---

ステップ 2：ライセンス

cdatacli で接続できても、ライセンスが有効になったことを意味するわけではありません。 cdatacli は JDBC ドライバーで動作するため、確認できるのは JDBC のライセンスのみです。ODBC ドライバーには別のライセンスが必要です。

CData ODBC ドライバーは、インストール時にライセンスが適用されます（セットアップウィザードまたは CData ライセンスツールで、トライアル版またはプロダクトキーが適用されます）。ライセンスはマシンごとであり、 JDBC／ADO.NET／Python エディションとは別です。ドライバーがすでにインストールされ、ライセンスが適用されている マシンでは、追加の操作は不要です。

ライセンスエラーでクエリが失敗する場合、ユーザーはインストーラーまたは CData ライセンスツールを使って ODBC ドライバーを再度有効化してください（プロダクトキーは秘密情報です。AI コーディングセッションの外で 操作してください）。有効化の詳細はインストーラーやプラットフォームによって異なるため、ここではスクリプト化した 手順ではなく、CData ODBC ドライバー独自のセットアップ手順に従ってください。

---

ステップ 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 が存在する場合は、ステップ 4 に進み、DSN=<name> を使って接続します。存在しない場合は、以下の手順で設定します。

接続方法は、名前付きの保存済み設定である DSN と、完全な接続文字列をコードに記述する DSN なし の 2 通りです。どちらの場合も、検出時に検証したプロパティを再利用してください。また、OAuth を使うデータソースでは、 OAuthSettingsLocation を検出時のトークンキャッシュに指定することで、DSN／接続文字列に秘密情報を保存せず、 ブラウザーフローも起動しないようにします。

オプション A — DSN（再利用におすすめ）

ユーザー DSN は管理者権限が不要で、現在のユーザーに限定されます。システム DSN はマシン全体で使用され、 管理者権限が必要です。キャッシュ済みの OAuth トークンを再利用してユーザー DSN を作成します。

# 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。

オプション B — DSN なし（自己完結型）

ドライバー名とすべてのプロパティを接続文字列に指定します。事前登録は不要です。

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

Driver={...} の値は、ステップ 1 に記載されているドライバー名と完全に一致させる必要があります。

秘密情報： OAuth が組み込まれたデータソース（例：Salesforce）では、キャッシュ済みのトークンだけが必要です。 OAuth アプリが組み込まれていないデータソース（例：Gmail）では、トークンの更新にもユーザー自身の OAuthClientId／OAuthClientSecret が必要です。実行時に環境変数から渡し、チェックインする DSN や接続文字列には 絶対に記述しないでください。

---

ステップ 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 を使ってください。

---

ステップ 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 バージョンとプラットフォームを使用していることを確認するか、フォールバックのネイティブビルド用にビルドツールをインストールしてください。