cdata-cli-python

スキル：CData CLI — Python ビルド

cdata-cli スキルをビルド段階で補完するスキルです。cdata-cli は JDBC ドライバーを使った検出（接続、スキーマの探索、SQL の検証）を担当します。CData Python Connector を使用して Python アプリケーションのコードを書き始めたら、このスキルに切り替えます。

検出時に検証した内容はすべてそのまま引き継げます。すべての CData ドライバーで同じリレーショナルモデルと SQL 方言を共有するため、cdatacli で確認したテーブル名、カラム名、SQL は Python Connector でも変更せずに使えます。

---

言語／ドライバーのエディション

言語	CData エディション	Python のインポート
Python 3.x	CData Python Connector	import cdata.<source>

<source> はドライバー名を小文字にしたものです。例：cdata.salesforce、cdata.gmail、cdata.snowflake。コネクターは、コンパイル済みの DB-API 2.0 モジュール（.pyd／.so）と SQLAlchemy 方言を含む、プラットフォーム固有のホイールとして提供されます。

---

前提条件：先に検出を完了する

このセッションでまだ cdata-cli を使用していない場合は、作業を止めて、先に実行してください。 このスキルが対象とするのはビルド段階のみです。ここで作業を続ける前に、cdata-cli を使って接続を設定し、スキーマを検出し、SQL を検証する必要があります。

このスキルでは、すでに cdata-cli を使って次のことを完了している前提です。

• ソースに接続できることを確認する。
• アプリで実行する正確なテーブル／カラムと SQL を検証する。

ここではその結果を再利用してください。特に、検出時にブラウザーでのサインインを行う OAuth 接続を cdatacli で作成した場合は、OAuthSettingsLocation を控えておいてください。Python アプリから同じキャッシュ済みトークンファイルを指定すれば、再認証を省略できます（「接続」を参照）。

実行時に CLI が直接扱うのは Java／JDBC のみです。 Python Connector のインストール、有効化、または接続の作成はできません。それらについてはこのスキルで説明します。Python Connector は別のランタイムドライバーエディションであり、個別に入手してライセンスを取得する必要があります（以下の手順を参照）。

CLI の drivers download が取得するのは JDBC jar のみです。Python ホイールは、CData の Python リポジトリから通常の HTTP 経由で取得します（以下を参照）。

---

手順 1：コネクターのホイールを入手する

CData Python Connector は、参照可能なインデックス（通常の HTTP、API も認証も不要）として https://maven.cdata.com/python/ で公開されています。

1. アーティファクトを探します：cdata-<source>-connector（例：cdata-salesforce-connector）。
2. 最新バージョンのフォルダーを開きます（例：26.0.9655）。
3. 対象の OS／アーキテクチャに合うホイールを選びます。

プラットフォーム	ホイールのサフィックス
Windows x64	...-win_amd64.whl
Linux x64	...-linux_x86_64.whl
macOS Apple Silicon	...-macosx_<ver>_arm64.whl

cp310-abi3 タグは、安定 ABI を持つ Python 3.10 以降を意味します。1 つのホイールで Python ≥ 3.10 のすべてをカバーします。

ダウンロードします（ファイルを検証してください。サーバーが転送中に接続を切断することがあります）。

# bash
curl -fSL --retry 3 --retry-all-errors -o cdata_<source>_connector-<ver>-cp310-abi3-win_amd64.whl \
  "https://maven.cdata.com/p/python/cdata-<source>-connector/<ver>/cdata_<source>_connector-<ver>-cp310-abi3-win_amd64.whl"

# PowerShell — curl.exe is more robust here than Invoke-WebRequest
curl.exe -fSL --retry 3 --retry-all-errors -o "cdata_<source>_connector-<ver>-cp310-abi3-win_amd64.whl" `
  "https://maven.cdata.com/p/python/cdata-<source>-connector/<ver>/cdata_<source>_connector-<ver>-cp310-abi3-win_amd64.whl"

.whl は zip ファイルです。アーカイブとして開けない場合は、ファイルが途中で切れています。再ダウンロードしてください。

すでにローカルにインストール済みですか？ CData 製品のバンドルからコネクターをインストールしている場合は、ダウンロードせずにそのホイールを使用できます。展開先のパスを確認してください。

<install-path>\CData.Python.<Source>\win\Python<ver>\64\cdata_<source>_connector-...whl   # Windows
<install-path>/CData.Python.<Source>/linux/cdata_<source>_connector-...tar.gz             # Linux/macOS

---

手順 2：コネクターをインストールする

アプリの実行に使用するインタープリターにホイールをインストールします。

python -m pip install cdata_<source>_connector-<ver>-cp310-abi3-win_amd64.whl

仮想環境の使用を推奨します（インストールをプロジェクト内に限定でき、ライセンスツールのパスも予測しやすくなります）が、必須ではありません。グローバルにインストールしても同様に動作します。

python -m venv .venv    # optional; activate, then pip install into it

モジュールをインポートできることを確認します。

python -c "import cdata.<source> as m; print('paramstyle:', m.paramstyle, '| apilevel:', m.apilevel)"
# expect: paramstyle: qmark | apilevel: 2.0

---

ステップ 3：ライセンスを有効化する

cdatacli への接続が成功しても、有効化されたことにはなりません。 cdatacli は JDBC ドライバー上で動作するため、JDBC のライセンスが有効であることしか確認できません。Python Connector には別途ライセンスが必要です。

Python Connector は JDBC／ADO.NET／ODBC 版とは別にライセンスされており、マシンごとにライセンスが必要です。有効化されていない場合、最初のクエリで "Could not find a valid license…" というエラーが発生します。

アクティベーターは、インストール済みパッケージの、使用中のインタープリターの site-packages/cdata/installlic_<source>/ に含まれています（次のコマンドで場所を確認できます： python -c "import cdata, os; print(os.path.dirname(cdata.__file__))"）：

installlic_<source>/install-license.exe   # Windows
installlic_<source>/install-license.sh    # macOS/Linux

アクティベーターは専用のフォルダーから実行してください（カレントディレクトリの prod.inf を読み込みます）。非対話形式で実行するには --name／--email を指定します（ビルド 26.0.9704 以降。これより前のビルドではプロンプトが表示されるため、通常のターミナルでユーザーが実行する必要があります）。macOS／Linux では ./install-license.sh を使用してください：

cd <installlic_<source> folder>       # path located above
./install-license.exe --name "First Last" --email [email protected]               # trial — safe to run here
./install-license.exe --name "First Last" --email [email protected] <PRODUCT-KEY> # key is a secret — user runs outside the AI session

有効化後にインポート／クエリの確認を再実行し、反映されたことを確認してください。

---

ステップ 4：接続する（DB-API 2.0）

import cdata.<source> as mod

conn = mod.connect(CONNECTION_STRING)   # a full CData connection string
cur = conn.cursor()
cur.execute("SELECT Id, Name FROM Account WHERE Name LIKE ?", ["%Acme%"])
rows = cur.fetchall()

• paramstyle は qmark です。プレースホルダーには ? を使用し、execute にはリストを渡してください。ユーザー入力は必ずパラメーター化し、SQL の文字列フォーマットは使用しないでください。
• INSERT／UPDATE／DELETE の後には conn.commit() を呼び出してください。

接続文字列と認証（検出時の設定を再利用し、シークレットをコードに含めない）

cdatacli で検証したものと同じプロパティを渡してください。OAuth ソースの場合、検出接続ですでに入力されたトークンファイルを OAuthSettingsLocation に指定すると、ブラウザ認証フローなしでアプリがトークンをサイレントに更新します：

# Embedded-OAuth source (e.g. Salesforce) — cached token is sufficient:
cs = ("AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;"
      r"OAuthSettingsLocation=C:\...\CData\Salesforce Data Provider\OAuthSettings-xxx.txt")

---

ステップ 5：エンドツーエンドの例

フレームワークに依存しません（必要に応じて Flask／FastAPI／Tkinter などでラップしてください）：

import cdata.salesforce as sf

CS = ("AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true;"
      r"OAuthSettingsLocation=C:\...\OAuthSettings-sbx.txt")

def get_conn():
    return sf.connect(CS)

def list_accounts(search=None, limit=50):
    conn = get_conn()
    try:
        cur = conn.cursor()
        sql = "SELECT Id, Name, Industry FROM Account"
        params = []
        if search:
            sql += " WHERE Name LIKE ?"; params.append(f"%{search}%")
        sql += f" ORDER BY Name LIMIT {int(limit)}"
        cur.execute(sql, params)
        return cur.fetchall()
    finally:
        conn.close()

def create_account(name, industry=None):
    conn = get_conn()
    try:
        cur = conn.cursor()
        cur.execute("INSERT INTO Account (Name, Industry) VALUES (?, ?)", [name, industry])
        conn.commit()
    finally:
        conn.close()

if __name__ == "__main__":
    for row in list_accounts(limit=5):
        print(row)

---

SQLAlchemy（任意）

この wheel には SQLAlchemy ダイアレクトもインストールされるため、ORM／エンジンのコードも動作します：

• cdata.sqlalchemy_<source> — SQLAlchemy 1.4 スタイルのダイアレクト
• cdata.sqlalchemy2_<source> — SQLAlchemy 2.0 スタイルのダイアレクト

from sqlalchemy import create_engine, text
# URL form: <source>:///?<connection-string-properties>
engine = create_engine("salesforce:///?AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;UseSandbox=true")
with engine.connect() as c:
    print(c.execute(text("SELECT COUNT(*) FROM Account")).scalar())

---

トラブルシューティング

エラー	原因／対処方法
Could not find a valid license for using CData Python Driver for <source>	このマシンで Python Connector が有効化されていません。install-license を実行してください（ステップ 3）。JDBC／ADO.NET／ODBC のライセンスとは別です。
'OAuthClientId' and 'OAuthClientSecret' are needed to initiate OAuth	ソースに組み込みの OAuth アプリがありません。接続文字列にクライアント ID／シークレットを指定してください（環境変数から取得）。キャッシュされたリフレッシュトークンに対応するアプリと一致している必要があります。
object does not support the context manager protocol	with mod.connect(...) を使用しています。明示的な try/finally に置き換えてください。
ModuleNotFoundError: No module named 'cdata.<source>'	使用中のインタープリターに wheel がインストールされていません。仮想環境が有効になっていること、または wheel がインストールされていることを確認してから、import cdata.<source> を再確認してください。
install-license.exe が応答しなくなる、または prod.inf でエラーになる	専用のフォルダーから --name／--email を指定して実行してください（ステップ 3）。指定しないとプロンプトで待機します。26.0.9704 より前のビルドはこれらのフラグをサポートしていません。アップグレードするか、ユーザーに対話形式で実行してもらってください。