API を使用して外部アプリを Lakebase に接続する

備考

Lakebase オートスケールは次のリージョンで利用できます: us-east-1 、 us-east-2 、 us-west-2 、 eu-central-1 、 eu-west-1 、 ap-south-1 、 ap-southeast-1 、 ap-southeast-2 。

Lakebase オートスケールは、オートスケール コンピュート、ゼロへのスケール、分岐、即時復元を備えた Lakebase の最新バージョンです。 Lakebase プロビジョニングとの機能の比較については、 「バージョン間の選択」を参照してください。

このガイドでは、直接REST API呼び出しを使用して外部アプリケーションを Lakebase オートスケールに接続する方法を説明します。 Databricks SDKがあなたの言語で利用できない場合（Node.js、Ruby、PHP、Elixir、Rust など)。

ご使用の言語で SDK がサポートされている場合 (Python、Java、または Go)、代わりにSDK を使用して外部アプリを Lakebase に接続することで、トークン管理を簡素化できます。

OAuth トークンのローテーションを使用してデータベース資格情報を取得するには、2 つの API 呼び出しを行います。curl と Node.js の例が提供されています。

注記

2 段階認証: このアプローチでは、データベース資格情報ごとに 2 つのAPI呼び出しが必要です。(1) サービス プリンシパル シークレットをワークスペースOAuthトークンに交換し、(2) OAuthトークンをデータベース資格情報に交換します。 両方のトークンは 60 分後に期限切れになります。SDK はステップ 1 を自動的に処理します。

前提条件

SDKアプローチと同じ設定 (サービスプリンシパル、Postgres ロール、接続の詳細) が必要です。

前提条件	重要な詳細	詳細情報
サービスプリンシパル	最大有効期間が 730 日 のOAuthシークレット。 ワークスペースへのアクセス を有効にします。 Postgres ロールと環境変数の クライアント ID (UUID) をメモします。	サービスプリンシパルを作成
Postgresの役割	Lakebase SQL エディターで OAuth ロールを作成します: databricks_create_role('{client-id}', 'SERVICE_PRINCIPAL') 、CONNECT、USAGE、SELECT/INSERT/UPDATE/DELETE を付与します。ステップ 1 のクライアント ID を使用します。	Postgresロールを作成する
接続の詳細	Lakebase Console Connect から: エンドポイント名 ( projects/.../branches/.../endpoints/... )、 ホスト 、 データベース (通常はdatabricks_postgres )。	接続の詳細を取得する

仕組み

手動 API アプローチでは、2 つのトークン交換が必要です。

トークンの有効期間:

• サービスプリンシパルシークレット: 最大 730 日間 (作成時に設定)
• ワークスペースOAuthオフライン: 60 分 (ステップ 1)
• データベース認証情報: 60 分 (ステップ 2)

トークンのスコープ: データベース資格情報はワークスペース スコープです。endpoint問題が必要である間、返されたノートは、サービスプリンシパルが権限を持つワークスペース内の任意のデータベースまたはプロジェクトにアクセスできます。

環境変数を設定する

アプリケーションを実行する前に、次の環境変数を設定します。

Bash

# Databricks workspace authentication
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_CLIENT_ID="<service-principal-client-id>"
export DATABRICKS_CLIENT_SECRET="<your-oauth-secret>"

# Lakebase connection details (from prerequisites)
export ENDPOINT_NAME="projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
export PGHOST="<endpoint-id>.database.<region>.databricks.com"
export PGDATABASE="databricks_postgres"
export PGUSER="<service-principal-client-id>"   # Same UUID as client ID
export PGPORT="5432"

接続コードを追加する

curl

この例では、生の API 呼び出しを示します。本番運用アプリケーションの場合は、内部キャッシュと更新ロジックを実装します。

Bash

# Step 1: Get workspace OAuth token
OAUTH_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/oidc/v1/token" \
  -u "${DATABRICKS_CLIENT_ID}:${DATABRICKS_CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=all-apis" \
  | jq -r '.access_token')

echo "Got workspace OAuth token (60-min lifetime)"

# Step 2: Get database credential
PG_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/api/2.0/postgres/credentials" \
  -H "Authorization: Bearer ${OAUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"endpoint\": \"${ENDPOINT_NAME}\"}" \
  | jq -r '.token')

echo "Got database credential (60-min lifetime)"

# Step 3: Connect to Postgres
PGPASSWORD="${PG_TOKEN}" psql \
  -h "${PGHOST}" \
  -p "${PGPORT}" \
  -U "${PGUSER}" \
  -d "${PGDATABASE}" \
  -c "SELECT current_user, current_database()"

Node.js

この例では、トークンの取得とキャッシュを処理する非同期パスワード関数を備えた node-postgres を使用します。

JavaScript

import pg from 'pg';

// Step 1: Fetch workspace OAuth token
async function getWorkspaceToken(host, clientId, clientSecret) {
  const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
  const response = await fetch(`${host}/oidc/v1/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${auth}`,
    },
    body: 'grant_type=client_credentials&scope=all-apis',
  });

  if (!response.ok) {
    throw new Error(`OAuth failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.access_token,
    expires: Date.now() + data.expires_in * 1000,
  };
}

// Step 2: Fetch database credential
async function getPostgresCredential(host, workspaceToken, endpoint) {
  const response = await fetch(`${host}/api/2.0/postgres/credentials`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${workspaceToken}`,
    },
    body: JSON.stringify({ endpoint }),
  });

  if (!response.ok) {
    throw new Error(`Database credential failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.token,
    expires: new Date(data.expire_time).getTime(),
  };
}

// Simple caching wrapper (production: use more sophisticated caching)
function cached(fetchFn) {
  let cache = null;
  return async (...args) => {
    const now = Date.now();
    if (!cache || now >= cache.expires - 5 * 60 * 1000) {
      // Refresh 5 min early
      const result = await fetchFn(...args);
      cache = result;
    }
    return cache.token;
  };
}

// Create connection pool with async password function
function createPool() {
  const host = process.env.DATABRICKS_HOST;
  const clientId = process.env.DATABRICKS_CLIENT_ID;
  const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;
  const endpoint = process.env.ENDPOINT_NAME;

  const cachedWorkspaceToken = cached(() => getWorkspaceToken(host, clientId, clientSecret));
  const cachedPostgresToken = cached(async () => {
    const workspaceToken = await cachedWorkspaceToken();
    return getPostgresCredential(host, workspaceToken, endpoint);
  });

  return new pg.Pool({
    host: process.env.PGHOST,
    port: process.env.PGPORT,
    database: process.env.PGDATABASE,
    user: process.env.PGUSER,
    password: cachedPostgresToken, // Async function: () => Promise<string>
    ssl: { rejectUnauthorized: true },
    min: 1,
    max: 10,
    idleTimeoutMillis: 900000, // Example: 15 minutes
    connectionTimeoutMillis: 60000, // Example: 60 seconds
  });
}

// Use the pool
const pool = createPool();
const result = await pool.query('SELECT current_user, current_database()');
console.log('Connected as:', result.rows[0].current_user);

依存関係: pg (node-postgres)

注意: Node-postgres ( pg ) は、パスワードとして非同期関数を受け入れます。この関数は新しい接続が作成されるたびに呼び出され、新しいトークンが確保されます。

実行して接続を確認する

curl

環境変数がロードされた状態で bash スクリプトを実行します。

Bash

export $(cat .env | xargs)
bash connect.sh

期待される出力:

Got workspace OAuth token (60-min lifetime)
Got database credential (60-min lifetime)
     current_user      | current_database
-----------------------+------------------
 c00f575e-d706-4f6b... | databricks_postgres

current_userサービスプリンシパル クライアント ID と一致する場合、 OAuth正しく機能しています。

Node.js

依存関係をインストールします:

Bash

npm install pg

ラン：

Bash

node app.js

期待される出力:

Connected as: c00f575e-d706-4f6b-b62c-e7a14850571b

注: Lakebase オートスケールはゼロからコンピュートを開始するため、アイドル後の最初の接続には時間がかかる場合があります。

トラブルシューティング

エラー	修正
「invalid_client」または「クライアント認証がありません」	DATABRICKS_CLIENT_IDとDATABRICKS_CLIENT_SECRETが正しいことを確認してください。基本認証（base64 エンコード）を使用します。
「ワークスペースへのアクセス権限のないユーザーに対しては API が無効になっています」	サービスプリンシパルの「ワークスペースアクセス」を有効にします（前提条件）。
"INVALID_PARAMETER_VALUE" / "フィールド 'endpoint' は必須です"	endpoint projects/<id>/branches/<id>/endpoints/<id>の形式でステップ 2 POST 本文に含まれていることを確認してください。
「ロールが存在しません」または認証に失敗しました	SQL 経由で OAuth ロールを作成します (前提条件)。
「接続が拒否されました」またはタイムアウト	スケール トゥ ゼロ後の最初の接続には時間がかかる場合があります。再試行ロジックを実装します。
トークンの有効期限が切れました / 「パスワード認証に失敗しました」	ワークスペース トークンとデータベース トークンはどちらも 60 分後に期限切れになります。有効期限チェック付きのキャッシュを実装します。