CData Connect AI には、社内ネットワークやVPC内のデータソースへ インバウンドポートを一切開けずに 接続するための「Connect Gateway」という機能があります。ところが、Connect Gateway が対応しているコネクタの一覧に Oracle は含まれていません。これは「そのうち対応予定」という話ではなく、技術的な理由があります。Connect Gateway は SOCKS ベースのリバーストンネルとして動作しますが、Oracle への接続に使われる OCI（Oracle Call Interface）系のクライアントライブラリは SOCKS プロキシをサポートしていないためです。本記事では、この制約を回避するために Apache Avatica を「プロトコル変換の中継役」として社内ネットワークに立て、Connect AI からは Apache Phoenix コネクタとして扱うことで、インバウンドポート開放なしにオンプレミスの Oracle Database へ接続する構成を、Docker ベースの手順として解説します。なお、Windows 中継サーバー上で CData SQL Gateway を使う別解については、関連記事「Connect AIからオンプレミスOracle DBへ接続する方法：SQL Gatewayによる中継構成ガイド」をご覧ください。両者の使い分けは本記事の最後で整理しています。

前提条件

• Docker Engine 20.10 以降（Docker Compose v2）が動作する Linux ホスト、または Kubernetes 1.25 以降のクラスタ

  • ホストは Oracle Database へ Oracle Net（通常 1521/tcp）で到達できること

• CData Connect AI アカウント（Connect Gateway が有効化されていること、ならびにロケーションを作成できる管理者権限）

• CData JDBC Driver for Oracle（cdata.jdbc.oracleoci.jar）とライセンスファイル（cdata.jdbc.oracleoci.lic）

• Linux 用ネイティブライブラリ一式（ドライバーパッケージに同梱。詳細は「手順2」を参照）

• Oracle への接続情報：ホスト名／IP、リスナーポート、Service Name、ユーザー名、パスワード

• Docker ホストから以下への アウトバウンド通信が許可されていること

  • cloud.cdata.com、*.cdata.com、*.servicebus.windows.net、*.azurecr.io

ネットワーク機器の TLS インスペクションに注意 上記3つのドメインに対して SSL/TLS インスペクション（復号検査）が有効になっていると、Connect Gateway が Azure Relay へのトンネルを確立できません。ネットワークチームに バイパス設定を依頼してください。これは後述のトラブルシューティングでも最も多いつまずきポイントです。

全体構成

本構成は、社内ネットワーク内に「Avatica コンテナ」と「Connect Gateway コンテナ」の2つを立て、Connect AI からはアウトバウンド通信のみで到達させる形になります。

社外に出ていくのは Connect Gateway からの アウトバウンド HTTPS のみです。Oracle への接続も、JDBC ドライバーもすべて社内側に閉じています。

なぜ Avatica を挟むのか

CData JDBC Driver for Oracle は、そのままでは Connect Gateway のトンネルを通れません（前述の SOCKS 非対応の問題）。そこで、JDBC 接続を HTTP 上のプロトコルとして外に見せるサーバーが必要になります。それが Apache Avatica Standalone Server です。Avatica は「JDBC 接続を HTTP + protobuf で公開する薄いサーバー」であり、Connect Gateway から見れば単なる TCP/HTTP のエンドポイントです。SOCKS の制約を受けるのは Oracle クライアントライブラリだけなので、その部分を社内側に閉じ込めてしまえば問題は解消します。

なぜ「Apache Phoenix」コネクタなのか

Connect AI 側で選ぶコネクタは、必ず「Apache Phoenix」 です。Avatica は HTTP 上で protobuf をやり取りする独自の「Avatica ワイヤプロトコル」を話すサーバーであり、PostgreSQL や MySQL のワイヤプロトコルは理解できません。たとえば「PostgreSQL」コネクタを選ぶと、Connect AI は本物の PostgreSQL の通信（StartupMessage など）を送ってしまい、Avatica 側で 400 Bad Request となって接続に失敗します。一方 Apache Phoenix は、もともと Avatica をベースに構築されたクエリエンジンです。そのため Connect AI の「Apache Phoenix」コネクタは、最初から Avatica の protobuf-over-HTTP を話す実装になっています。Apache Phoenix は Connect Gateway の対応ソースにも含まれているため、Gateway 経由での利用も想定どおりに動作します。

設定手順

1. Oracle 側にサービスアカウントを用意する

Connect AI 用に、専用のデータベースユーザーを作成します。推奨する属性は次のとおりです。

公開対象のスキーマ名・テーブル名は、後の手順で JDBC URL に明示的に書き込むため、ここでリストアップしておいてください。

2. 必要なファイルを集める

作業用ディレクトリを作り、以下のファイルを配置します。

Avatica Standalone Server の jar を入手する

avatica-standalone-server-1.28.0.jar は Apache Calcite Avatica の公式リリース成果物で、Maven Central から誰でも直接ダウンロードできます。ビルドや Maven プロジェクトの作成は不要です。

cd oracle-avatica
curl -LO https://repo1.maven.org/maven2/org/apache/calcite/avatica/avatica-standalone-server/1.28.0/avatica-standalone-server-1.28.0.jar

ファイルサイズは約15MBです。このjarはJettyなどの依存関係をすべて内包した実行可能jar（shadow jar）になっているため、これ1つで Avatica サーバーが起動します。同じディレクトリに -shadow という classifier 付きのjarも置かれていますが、中身は上記のjarと同一です。どちらを使っても構いません。

ダウンロードしたファイルが壊れていないかは、公式の SHA-1 と突き合わせて確認できます。

curl -Ls https://repo1.maven.org/maven2/org/apache/calcite/avatica/avatica-standalone-server/1.28.0/avatica-standalone-server-1.28.0.jar.sha1
sha1sum avatica-standalone-server-1.28.0.jar

2つの値が一致すればOKです。より厳密に検証したい場合は、同ディレクトリの .asc（PGP署名）と Apache の KEYS ファイルを使った署名検証も可能です。

バージョンについて 本記事の検証時点で 1.28.0 が最新版です。別のバージョンを使いたい場合は、URLの 1.28.0 の部分を差し替えてください。入手可能なバージョンは Maven Central のディレクトリで確認できます。バージョンを変えた場合は、Dockerfile 内のファイル名も忘れずに合わせてください。

インターネットに出られないサーバーで作業する場合 Maven Central へアクセスできる端末でjarをダウンロードし、ファイルとして持ち込んでください。特別なライセンス手続きは不要です（Apache License 2.0）。

Linux 用ネイティブライブラリについて

CData JDBC Driver for Oracle は Oracle OCI をラップする作りのため、Java からネイティブライブラリを呼び出します。Linux 上で動かす場合は、Linux 用のネイティブライブラリ一式が必要です。これらはドライバーパッケージに同梱されています。インストール先の lib/native/ 配下を確認し、libSystem.Data.CData.OracleOCIw.so と Oracle OCI クライアントライブラリ（libclntsh.so.* など）を上記の native-linux/ にコピーしてください。

ファイルが見当たらない場合 お使いのパッケージ形態やバージョンによっては Linux 用ライブラリが含まれていないことがあります。その場合は CData サポートデスクへ「Oracle JDBC ドライバーの Linux 用ネイティブライブラリ一式が欲しい」とご連絡ください。ライセンスをお持ちのお客様には個別にご案内しています。.so ファイルのバージョン番号（例：23.1）は入手したパッケージによって異なります。Dockerfile 内のファイル名と実際のファイル名は必ず一致させてください。 不一致のまま進めると、ビルド自体は成功するのにライブラリが1つも入っていない状態になり、接続時に原因の分かりにくいエラーになります。

3. Docker イメージをビルドする

Dockerfile を以下の内容で作成します。

FROM eclipse-temurin:21-jre-jammy

# Oracle OCI ネイティブライブラリの実行に必要な OS パッケージ
RUN apt-get update && apt-get install -y --no-install-recommends \
    libaio1 libstdc++6 zlib1g libgcc-s1 \
    && rm -rf /var/lib/apt/lists/*

# Linux 用ネイティブライブラリを配置
RUN mkdir -p /opt/oracle/instantclient
COPY native-linux/*.so* /opt/oracle/instantclient/
RUN ln -s /opt/oracle/instantclient/libclntsh.so.23.1     /opt/oracle/instantclient/libclntsh.so \
    && ln -s /opt/oracle/instantclient/libclntshcore.so.23.1 /opt/oracle/instantclient/libclntshcore.so \
    && ln -s /opt/oracle/instantclient/libocci.so.23.1       /opt/oracle/instantclient/libocci.so

# JVM がネイティブライブラリを見つけられるようにする
ENV LD_LIBRARY_PATH=/opt/oracle/instantclient

# CData Oracle JDBC ドライバーとライセンス
RUN mkdir -p /opt/drivers
COPY drivers/cdata.jdbc.oracleoci.jar /opt/drivers/
COPY drivers/cdata.jdbc.oracleoci.lic /opt/drivers/

# Avatica Standalone Server
COPY avatica-standalone-server-1.28.0.jar /opt/

WORKDIR /opt
EXPOSE 8765

ENTRYPOINT ["/bin/sh", "-c", "\
  exec java -cp '/opt/avatica-standalone-server-1.28.0.jar:/opt/drivers/*' \
    org.apache.calcite.avatica.standalone.StandaloneServer \
    -p 8765 \
    -s protobuf \
    -u \"$AVATICA_JDBC_URL\" \
"]

ビルドします。

docker build -t cdata-oracle-avatica:1.0.0 ./oracle-avatica

ビルド直後に必ず確認してください。 ネイティブライブラリが実際にイメージへ入っているかをチェックします。

docker run --rm cdata-oracle-avatica:1.0.0 ls /opt/oracle/instantclient

libSystem.Data.CData.OracleOCIw.so や libclntsh.so などが表示されればOKです。ディレクトリが空だったり存在しない場合は、native-linux/ に置いたファイル名と Dockerfile の記述が食い違っています。

4. JDBC 接続文字列を組み立てる

Avatica に渡す JDBC URL を用意します。

jdbc:oracleoci:<ユーザー>;Password=<パスワード>;Server=oracle-prod.internal.example.com;Port=1521;ServiceName=<サービス>;BrowsableSchemas=<スキーマ>;Tables=<テーブル>;QueryPassthrough=false;SupportEnhancedSQL=true;

指定すべきプロパティの意味は次のとおりです。

AuthScheme は指定しないでください 他の CData ドライバーの感覚で AuthScheme を書くと、'authscheme' is not a valid connection property というエラーになります。本ドライバーにこのプロパティは存在しません。Oracle が Docker ホスト自身の上で動いている場合、コンテナ内の localhost はコンテナ自身を指してしまいます。Server にはホストのブリッジIP、または host.docker.internal を指定してください。

5. Connect AI で Connect Gateway のロケーションを登録する

ここから Connect AI の画面操作です。

1. Connect AI にログインし、Sources →Add Connection をクリックします（既存コネクションを編集する場合は、そのコネクションの編集画面を開きます）。

2. Apache Phoenix を選択します。

3. Add/Edit Connection 画面の Gateways タブを開きます。

4. Add をクリックすると「Add Gateway」ダイアログが表示されます。

5. ゲートウェイを設置する場所が分かる名前を入力し、Confirm をクリックします。

一覧に追加されたロケーションから、以下の3つの値をコピーして控えておきます（目のアイコンで Key を表示、コピーアイコンでコピーできます）。

6. Avatica と Connect Gateway を起動する

Docker Compose の場合

.env ファイルに接続情報をまとめます。

AVATICA_JDBC_URL=jdbc:oracleoci:User=<ユーザー>;Password=<パスワード>;Server=oracle-prod.internal.example.com;Port=1521;ServiceName=<サービス>;BrowsableSchemas=<スキーマ>;Table=<テーブル>;QueryPassthrough=false;SupportEnhancedSQL=true;

ACCOUNT_ID=
GATEWAY_LOCATION_ID=
GATEWAY_API_KEY=

docker-compose.yml を作成します。Connect Gateway コンテナから Avatica コンテナをコンテナ名で名前解決できるよう、必ず同一のネットワークに所属させるのがポイントです。

services:
  avatica:
    image: cdata-oracle-avatica:1.0.0
    container_name: avatica-oracle
    restart: unless-stopped
    environment:
      AVATICA_JDBC_URL: "${AVATICA_JDBC_URL}"
    ports:
      - "8765:8765"
    networks:
      - cdata

  gateway:
    image: connectaipublic.azurecr.io/connectgateway:latest
    container_name: connect-gateway
    restart: unless-stopped
    environment:
      ACCOUNT_ID: "${ACCOUNT_ID}"
      GATEWAY_LOCATION_ID: "${GATEWAY_LOCATION_ID}"
      GATEWAY_API_KEY: "${GATEWAY_API_KEY}"
    extra_hosts:
      - "host.docker.internal:172.22.0.1"
    depends_on:
      - avatica
    networks:
      - cdata

networks:
  cdata:
    driver: bridge
    ipam:
      config:
        - subnet: 172.22.0.0/16
          gateway: 172.22.0.1

サブネットを ipam で固定しているのは、ブリッジのゲートウェイIPが再起動のたびに変わらないようにするためです（セキュリティ強化済みの Linux で iptables ルールを恒久化する際に効いてきます）。

起動します。

docker compose up -d
docker compose logs -f

Avatica のログに Started Avatica server on port 8765 with serialization PROTOBUF が出れば起動成功です。

Kubernetes の場合

Connect Gateway は Helm チャートが公開されています。

helm repo add cdata https://cdatasoftware.github.io/connect-gateway-helm
helm repo update

helm install connect-gateway cdata/connect-gateway \
  --set gateway.locationId= \
  --set gateway.accountId= \
  --set gateway.apiKey= \
  -n connect-gateway --create-namespace

本番環境では API キーを --set で渡さないでください。 シェル履歴と Helm リリースの保存値に平文で残ります。Kubernetes Secret を作成し、--set existingSecret= を使う方法が推奨されています。

Avatica 側は、手順3でビルドしたイメージをレジストリに push したうえで Deployment + Service（ClusterIP、port 8765）としてデプロイします。JDBC URL は Secret から環境変数 AVATICA_JDBC_URL として渡してください。

ゲートウェイの稼働確認は次のコマンドで行えます。

kubectl get pods -n connect-gateway
kubectl logs -n connect-gateway -l app.kubernetes.io/name=connect-gateway -f

7. Avatica への疎通を確認する

Connect AI の設定に進む前に、ホストから Avatica が見えているかを確認しておくと、切り分けが一気に楽になります。

curl -v http://localhost:8765

期待される応答：HTTP/1.1 400 Bad Request と This server expects only POST calls というメッセージ。

一見エラーに見えますが、これは Avatica が正常に起動していてポートが公開されている証拠です。タイムアウトや Connection refused になる場合は、Avatica が起動していないか、ポートが塞がれています。

8. Connect AI 側で接続設定を完成させる

Connect AI の Add/Edit Connection 画面に戻ります。

1. Gateways タブで Test Gateways をクリックします。ステータスが Success に変われば、ゲートウェイのトンネルは確立しています。

2. Basic Settings タブに戻り、以下を設定します。

Database Product Name を Auto にしないでください Auto のままだと Connect AI が Phoenix 固有のセッション初期化SQL を送ってしまい、Oracle 側で拒否されます。CData を指定すると、この Phoenix 方言の処理が抑制されます。

3. Save & Test をクリックします。

Tables= で指定したテーブルが Data Model パネルに表示されれば完了です。

動作確認

Connect AI の Explorer から、実際に Oracle のデータを取得できるか確認します。

SELECT * FROM [YourConnectionName].[Schema_Name].[CUSTOMERS]

続けて、以下も確認しておくと運用開始後の安心感が違います。

• メタデータ：Data Model パネルでカラムの型が正しく取得できているか

• プレビュー：任意のテーブルを選んで Preview を実行し、行が返るか

• アドホッククエリ：Explorer から SELECT を実行し、数秒以内に完了するか

• 自然言語での問い合わせ：Claude などの MCP クライアントから Connect AI の MCP エンドポイントを指定し、Oracle のデータに対して業務的な質問を投げてみる

よくある質問・トラブルシューティング

本構成で実際に遭遇しやすい事象を、症状ベースでまとめます。

Q: Oracle のテーブルを追加したいときは？ A: ①Oracle 側でサービスアカウントに SELECT 権限を付与 → ②JDBC URL の Tables= に追記 → ③Avatica コンテナを再起動 → ④Connect AI のコネクションで Clear Metadata を実行し Save & Test、の順に進めてください。

Q: パスワードをローテーションしたい場合は？ A: Oracle 側でパスワードを変更 → .env（または Kubernetes Secret）の JDBC URL を更新 → Avatica を再起動、で反映されます。Connect AI 側の再設定は不要です。

Q: host-gateway という特殊値が使えません A: Amazon Linux 2023 など一部のディストリビューションでは extra_hosts の host-gateway が正しく解決されません。上のサンプルのように、ブリッジのゲートウェイIP（例：172.22.0.1）を明示的に指定してください。

制約事項

本構成を採用する前に、以下は把握しておいてください。

• ストアドプロシージャは部分的なサポートです。 結果セットを返す単純な呼び出しは動作しますが、OUT / INOUT パラメータを持つストアドプロシージャは動作しません。Avatica のクライアント側に CallableStatement の実装が無いためで、CData Oracle JDBC ドライバー自体の制約ではありません。

• Avatica 自体の認証はユーザー名／パスワードのみで、TLS もデフォルトでは無効です。Avatica のエンドポイントは社内ネットワーク内に閉じたまま運用し、外部に露出させないでください。

• Apache Avatica は CData 製品ではありません。 バージョン固定（本記事では 1.28.0）と Docker の運用は利用者側の責任範囲になります。本構成は CData の FDE（Forward Deployed Engineer）が検証したリファレンス構成であり、エンドツーエンドでの公式サポート対象外です。

• 本記事の対象は「プレーンな TCP（ホスト/ポート/サービス名）で接続できるオンプレミス Oracle」です。 OCI 上の Autonomous Database など、Wallet を使った mTLS 接続は対象外です。

SQL Gateway 構成との使い分け

オンプレミス Oracle への接続には、本記事の Avatica 構成のほかに、CData SQL Gateway を使う方法もあります（関連記事）。どちらを選ぶかは、ネットワークポリシーと運用体制次第です。

判断の目安

• 「社内ファイアウォールにインバウンド穴を開けることは絶対に認められない」→ 本記事の Avatica 構成

• 「Connect AI のエグレスIP範囲からの受信なら許可できる」「Windows サーバーで手早く済ませたい」→ SQL Gateway 構成

なお、SQL Gateway には SSH リバーストンネル機能も備わっているため、自社で踏み台サーバーを運用している場合は、SQL Gateway 構成でもインバウンド開放を回避できます。

まとめ

Connect Gateway が Oracle コネクタに対応していないのは技術的な制約によるものですが、Apache Avatica を「JDBC を HTTP に載せ替える中継役」として挟むことで、インバウンドポートを開けずに Connect AI からオンプレミス Oracle へ接続できます。

つまずきやすいポイントを改めて3つに絞ると、次のとおりです。

1. コネクタは「Apache Phoenix」を選ぶ（PostgreSQL ではありません）

2. JDBC URL に QueryPassthrough=false と BrowsableSchemas / Tables を必ず入れる

3. Database Product Name は CData に設定する（Auto は不可）

この3点を押さえておけば、残りは Docker と Connect Gateway の標準的な手順です。設定内容やエラーの原因が分からない場合は、お気軽に CData サポートデスクまでご連絡ください。