matlab-connect-databricks-jdbc

JDBC を使用して MATLAB を Databricks に接続する

Database Toolbox と MATLAB Interface for Databricks パッケージを使用して、MATLAB から Databricks への JDBC 接続を確立する場合に使用します。このスキルでは、接続クラスの選択、認証の設定、ドライバーのセットアップ、接続の最適化について説明します。接続後は、j.Connection オブジェクトに対して標準的な Database Toolbox 関数（sqlread、fetch、sqlwrite、execute）を使用してデータを操作します。

前提条件

• MATLAB Interface for Databricks パッケージがインストールされ、MATLAB パスに追加されていること
• Database Toolbox がインストールされていること

使用する場面

• JDBC 経由で MATLAB を Databricks クラスターに接続する場合
• JDBC 経由で MATLAB を Databricks SQL Warehouse に接続する場合
• Databricks 認証（PAT、OauthU2M、OauthM2M）を設定する場合
• Databricks JDBC ドライバー（Simba または OSS）をセットアップする場合
• Databricks パッケージ全体を使わずに、スタンドアロンの JDBC 接続を作成する場合
• Databricks クラスター上で MATLAB を実行し、JDBC 経由で接続し直す場合
• Databricks への大規模なデータ転送で書き込み性能を最適化する場合
• ユーザーが次のキーワードに言及した場合：Databricks、JDBCConnection、SQL Warehouse、databricks.JDBCConnection、StandaloneJDBCConnection、Databricks JDBC、Databricks connect、Databricks cluster、Databricks authentication

使用しない場面

• ODBC 経由で接続する場合（databricks.ODBCConnection を直接使用してください）
• Databricks Connect を使用する場合（Python ベースの Spark API であり、Database Toolbox ではありません）
• Databricks REST API（Clusters、Jobs、DBFS など）を使用する場合
• MATLAB から MLflow を使用する場合（パッケージ内の別モジュールです）
• Statement Execution REST API 経由で SQL を実行する場合（JDBC ではありません）

重要なルール

接続

• database() を使用して JDBC URL を手動で構築するより、必ず databricks.JDBCConnection または StandaloneJDBCConnection を優先してください。URL の手動構築は誤りではありませんが、URL の形式は複雑で間違いやすく、ソースコード内で接続情報が露出する可能性があります。接続クラスは、URL の構築、ドライバーのクラスパス、認証を自動的に処理します。
• ユーザーが MATLAB Interface for Databricks パッケージをインストールしていない場合は、必ず StandaloneJDBCConnection を使用してください。JDBC URL を手動で構築する database() に切り替えてはいけません。
• 接続が不要になったら、必ず close(j) または close(j.Connection) を呼び出してください。
• j.Connection.Message が空であることを確認し、接続が成功したか必ず検証してください。メッセージが空でない場合は、ドライバーエラーを示します。

認証

• 統合プロバイダーチェーンによる認証処理は、必ず接続クラスに任せてください。デフォルトの方法は OauthU2M です。トークンをソースコードにハードコードしないでください。
• ブラウザー上で MATLAB を Databricks 上で実行する場合、JDBC ドライバー組み込みの OauthU2M は絶対に使用しないでください。ドライバーはブラウザーウィンドウを開こうとしますが、これは失敗します。代わりに useDriverAuth=false を使用してください。

ドライバー

• Simba ドライバー（非 OSS、v2.7.3 以上 v3.0.0 未満）がデフォルトで、パッケージに同梱されています。MATLAB のデフォルトの Java 8 環境で動作します。
• OSS ドライバー（v3.0.3 以降）には Java 11 以上が必要です。使用する前に jenv で MATLAB の Java 環境を設定してください。OSS ドライバーは Arrow を使用して大規模なデータ転送を高速化します。
• StandaloneJDBCConnection がサポートするのは Simba ドライバーのみです。スタンドアロン接続では useDriverType="oss" を使用しないでください。

関数リファレンス

関数／クラス	目的	使用する場面
databricks.JDBCConnection	パッケージの全機能をサポートする JDBC 接続を作成します	MATLAB Interface for Databricks パッケージがインストールされている場合のデフォルトの選択肢です
StandaloneJDBCConnection	パッケージへの依存関係なしで JDBC 接続を作成します	Databricks 接続をスタンドアロンのコードベースに組み込む場合
databricks.SQLWarehouse.connect()	ID を指定して SQL Warehouse に接続し、database.jdbc.connection を直接返します	クラスターではなく SQL Warehouse を対象にする場合
j.Connection	JDBCConnection または StandaloneJDBCConnection の基盤となる database.jdbc.connection オブジェクトです	sqlread、fetch、sqlwrite、execute などに渡します。Database Toolbox で database() を使って作成した conn と同等です
databricks.internal.isOnDatabricks()	MATLAB が Databricks クラスター上で実行されている場合は true を返します	クラスター内とクラスター外の状況に応じて接続ロジックを分岐させる場合
j.testConnection()	接続が機能していることを確認します	接続を作成した後、成功を確認する場合
j.saveSource()	接続を Database Toolbox のデータソースとして保存します	Database Explorer アプリで対話的にデータを探索する場合
j.copyToken()	認証トークンをクリップボードにコピーします	Database Explorer で認証情報を求められた場合
close(j)	接続を閉じ、リソースを解放します	接続の使用を終えた場合

選択の指針

どのクラスを使用すればよいですか？

シナリオ	クラス	理由
パッケージがすべてインストールされていて、クラスターを対象にする	databricks.JDBCConnection	認証、URL、ドライバーのクラスパスを自動的に処理します
HTTP パスで特定のコンピュートエンドポイントを対象にする	databricks.JDBCConnection(httpPath="/sql/1.0/warehouses/abc")	デフォルトのクラスターへのルーティングを上書きします
パッケージがすべてインストールされていて、SQL Warehouse を対象にする	databricks.SQLWarehouse.connect()	REST API 経由でウェアハウスのメタデータから接続を構築します
パッケージが未インストール、またはスタンドアロンで統合する	StandaloneJDBCConnection	Databricks パッケージへの依存関係がありません
すでに databricks.Cluster オブジェクトを持っている	databricks.JDBCConnection(cluster=myCluster)	特定のクラスターオブジェクトに接続をルーティングします
MATLAB が Databricks クラスター上で実行されている	databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false)	ドライバーのブラウザー認証は、ブラウザー内の MATLAB では機能しません

どの JDBC ドライバーを使用すればよいですか？

シナリオ	ドライバー	備考
Java 8（MATLAB のデフォルト）	Simba（デフォルト）	パッケージに同梱されているため、設定は不要です
Java 11 以降が利用可能で、両方のドライバーが存在する	OSS（自動選択）	大容量転送のパフォーマンス向上のため、Arrow を使用します
明示的に制御する必要がある	useDriverType='oss' or 'simba'	自動選択を上書きします

ドライバーのインストールと Java の設定について詳しくは、references/driver-selection.md を参照してください。

どの認証方法を使用すべきですか？

シナリオ	認証方法	必要な設定
個人の対話的な利用（デフォルト）	OauthU2M	.databrickscfg 内の host
自動化サービスまたは CI/CD パイプライン	OauthM2M	.databrickscfg 内の host、client_id、client_secret
シンプルトークンベースのアクセス	PAT	.databrickscfg 内の host、token
.databrickscfg 内の複数のワークスペース	任意 + profileName="myprofile"	profileName 引数による .databrickscfg 内の名前付きプロファイル
Databricks クラスター上での実行	OauthU2M + useDriverAuth=false	パッケージ管理の認証（ドライバー管理ではない）
外部ソースからの不透明トークン	トークンパススルー	passthroughAccessToken 引数
Azure Entra ID マネージドワークスペース	OauthU2M + OauthService="EntraID"	スコープ解決を Databricks ネイティブではなく Azure AD に設定

.databrickscfg の形式や環境変数を含む認証設定の詳細については、references/authentication.md を参照してください。

一般的なパターン

パターン 1: クラスター接続（デフォルト）

% Connect to a Databricks cluster using default authentication
j = databricks.JDBCConnection();

% Use Database Toolbox functions on the connection
data = sqlread(j.Connection, "mycatalog.myschema.mytable");

% Close when done
close(j);

パターン 2: カタログとスキーマを使用したクラスター接続

% Set default catalog and schema to simplify table references
j = databricks.JDBCConnection(catalog="mycatalog", schema="myschema");

% Now table names do not need full qualification
data = sqlread(j.Connection, "mytable");

close(j);

パターン 3: SQL Warehouse 接続

% Create a warehouse object and set its ID
warehouse = databricks.SQLWarehouse;
warehouse.id = "abc123def456";

% Connect (defaults to JDBC mode)
conn = warehouse.connect();

% Query data
data = fetch(conn, "SELECT * FROM mycatalog.myschema.mytable LIMIT 10");

% Close when done
close(conn);

パターン 4: 書き込み最適化接続（Simba ドライバー）

Simba ドライバーの書き込みパフォーマンスは、ネイティブクエリモードで大幅に向上します。これは接続の作成時にデフォルトで有効になりますが、明示的に制御することもできます。

% Default behavior: UseNativeQuery=1, EnableNativeParameterizedQuery=0
j = databricks.JDBCConnection();
sqlwrite(j.Connection, "mycatalog.myschema.mytable", data);
close(j);

% To disable the optimization (not recommended for writes)
j = databricks.JDBCConnection(useNativeQuery=false, enableNativeParameterizedQuery=true);

SQL Warehouse の場合:

warehouse = databricks.SQLWarehouse;
warehouse.id = "abc123def456";
conn = warehouse.connect(useNativeQuery=true, enableNativeParameterizedQuery=false);
sqlwrite(conn, "mycatalog.myschema.mytable", data);
close(conn);

パターン 5: Databricks 上での接続

Databricks クラスター上で（ブラウザベースで）MATLAB を直接実行する場合、JDBC ドライバーの OAuth フローはブラウザーを開くことができません。代わりにパッケージ管理の認証を使用してください。環境は databricks.internal.isOnDatabricks() で検出します。

% Detect if running on Databricks
if databricks.internal.isOnDatabricks()
    j = databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false);
else
    j = databricks.JDBCConnection();
end

data = fetch(j.Connection, "SELECT * FROM mycatalog.myschema.mytable LIMIT 10");
close(j);

パターン 6: スタンドアロン接続（パッケージなし）

ユーザーが MATLAB Interface for Databricks パッケージをインストールしていない場合は、StandaloneJDBCConnection を使用します。このクラスには Database Toolbox と Simba JDBC ドライバーの jar のみが必要で、Databricks パッケージへの依存関係はありません。

セットアップ:

1. StandaloneJDBCConnection.m と databricks_standalone_jdbc_settings.json を MATLAB パスに配置します
2. JSON ファイルを host、orgId、clusterId、認証設定で編集します
3. 接続を構築します:

% Add standalone class folder to path (if not already)
addpath("path/to/standalone/folder");

% StandaloneJDBCConnection reads config from databricks_standalone_jdbc_settings.json
j = StandaloneJDBCConnection(schema="myschema", catalog="mycatalog");
data = fetch(j.Connection, "SELECT * FROM mytable LIMIT 10");
close(j);

JSON 設定ファイル（databricks_standalone_jdbc_settings.json）には以下を含める必要があります:

• host: Databricks ワークスペースの URL（例: "https://adb-123.1.azuredatabricks.net"）
• orgId: ワークスペースの org ID
• clusterId: クラスターまたは SQL Warehouse の ID
• jarFilePath: Simba JDBC ドライバーの jar へのパス

完全な JSON テンプレートとすべてのフィールドについては、references/standalone-jdbc.md を参照してください。

パターン 7: Database Explorer 統合

% Create and save a connection as a data source
j = databricks.JDBCConnection();
j.saveSource();

% Copy the token to clipboard for pasting into Database Explorer
j.copyToken();

% Open Database Explorer, select the saved data source,
% enter "token" as username, paste the token as password
databaseExplorer

パターン 8: エラーセーフな接続のクリーンアップ

onCleanup または try/catch を使用して、クエリが失敗した場合でも接続が確実に閉じられるようにします。

j = databricks.JDBCConnection(catalog="main", schema="analytics");
cleanup = onCleanup(@() close(j));

% If this errors, cleanup still runs
data = fetch(j.Connection, "SELECT * FROM large_table WHERE id > 1000");

よくある間違い

% NOT RECOMMENDED: manually constructing a JDBC URL with database()
% This works but is error-prone and may expose connection details in code
conn = database("default", "token", myToken, ...
    "com.databricks.client.jdbc.Driver", ...
    "jdbc:databricks://myhost:443/default;transportMode=http;ssl=1;...");
% RECOMMENDED: let JDBCConnection handle URL construction
j = databricks.JDBCConnection();
conn = j.Connection;

% WRONG: using driver auth when running MATLAB on Databricks
j = databricks.JDBCConnection();  % Driver tries to open a browser, fails
% CORRECT: disable driver auth in browser environment
j = databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false);

% WRONG: hardcoding a PAT token in source code
j = databricks.JDBCConnection(token="dapi1234567890abcdef");
% CORRECT: store token in .databrickscfg and let the auth chain find it
j = databricks.JDBCConnection(authMethod="PAT");

% WRONG: using the OSS driver with Java 8
j = databricks.JDBCConnection(useDriverType="oss");  % Error: Java 11+ required
% CORRECT: set Java version first, then use OSS driver
jenv("/path/to/java11");  % Requires MATLAB restart
j = databricks.JDBCConnection(useDriverType="oss");

% WRONG: forgetting to close the connection
j = databricks.JDBCConnection();
data = sqlread(j.Connection, "mytable");
% Connection left open, resources leaked
% CORRECT: always close
close(j);

Unity Catalog の命名

Unity Catalog によって管理されるリソースにアクセスする場合、ハイフンを含む名前は SQL クエリ内でバッククォートで囲む必要があります:

% Schema name contains a hyphen
data = fetch(j.Connection, "SELECT * FROM mycatalog.`my-schema`.mytable");

sqlread と sqlwrite の場合は、代わりに接続上でカタログとスキーマを設定します:

j = databricks.JDBCConnection(catalog="mycatalog", schema="my-schema");
data = sqlread(j.Connection, "mytable");

チェックリスト

Databricks JDBC 接続コードを最終確定する前に、以下を確認してください:

• databricks.JDBCConnection、StandaloneJDBCConnection、または SQLWarehouse.connect() を使用している（手動での database() URL 構築よりも推奨）
• シナリオに適した認証方法（対話的な利用には OauthU2M、サービスには OauthM2M、シンプルなアクセスには PAT）
• ソースコードにトークンやシークレットがハードコードされていない
• 完了時に close(j) または close(conn) が呼び出されている
• Databricks 上の場合: useDriverAuth=false が設定されている
• OSS ドライバーを使用する場合: jenv 経由で Java 11+ が構成されている
• Simba で大容量データを書き込む場合: UseNativeQuery 最適化が有効である（デフォルト）
• 空の j.Connection.Message または j.testConnection() で接続が検証されている

トラブルシューティング

問題：接続で database.jdbc.connection が空のまま返され、メッセージが表示される

• 解決策：j.Connection.Message プロパティを確認してください。よくある原因は、ホストの誤り、トークンの有効期限切れ、クラスターが起動していないこと、クラスパス上のドライバーの誤りです。

問題：「Driver class not found on Java class path」

• 解決策：JDBC ドライバーの jar が MATLAB の動的 Java クラスパスにありません。databricks.JDBCConnection は自動で追加します。StandaloneJDBCConnection の場合は、先に javaaddpath("path/to/Shaded-Databricks-JDBC-Driver-0.0.2.jar") を呼び出してください。

問題：OSS ドライバーで Java バージョンエラーが発生する

• 解決策：OSS ドライバーには Java 11 以降が必要です。jenv で確認し、互換性のある JDK を設定してください：jenv("/path/to/java11")。変更後は MATLAB を再起動してください。

問題：「An ODBC/JDBC datasource exists with the same name as the database」

• 解決策：保存済みのデータソースがスキーマと同じ名前になっています。データソースの名前を変更するか、別の dataSourceName 引数を使用してください。

問題：接続の確立に時間がかかる

• 解決策：Databricks クラスターまたは SQL Warehouse が停止状態から起動している可能性があります（コールドスタート）。数分かかることがあります。Databricks UI または warehouse.refresh() でクラスター／ウェアハウスの状態を確認してください。コンピューティングリソースの準備が整うまで、MATLAB は処理をブロックします。

問題：接続が停止する、またはタイムアウトする

• 解決策：クラスターまたは SQL Warehouse が起動していることを確認してください。SQL Warehouse の場合、warehouse.refresh() で現在の状態を確認できます。停止中のウェアハウスの起動中は、MATLAB が処理をブロックします。

問題：ドライバー v2.7.x で Linux/macOS 上のトークンキャッシュエラーが発生する

• 解決策：既知のドライバーの不具合です。ドライバーを v2.7.3 以降にアップグレードするか、キャッシュを無効にしてください：enableTokenCache=false。バージョンごとの詳細については、パッケージ内の JDBCWorkflow.md ドキュメントを参照してください。

問題：Databricks 上で MATLAB を実行すると OauthU2M が失敗する

• 解決策：JDBC ドライバーの OAuth フローはブラウザーを開こうとしますが、ブラウザーベースの MATLAB では失敗します。databricks.JDBCConnection(authMethod="OauthU2M", useDriverAuth=false) を使用してください。

まだ解決しませんか？ 詳しい説明については、同梱ドキュメントを参照してください：

doc databricks.JDBCConnection                          % Class reference
edit(databricksRoot(-2, "Documentation", "JDBCWorkflow.md"))  % JDBC workflow guide
edit(databricksRoot("Standalone", "README.md"))         % Standalone setup guide

上記の方法で問題が解決しない場合は、MATLAB-Databricks チームによる直接サポートを受けるため、[email protected] にメールでお問い合わせください。

---

Copyright 2026 The MathWorks, Inc.