Lakebase APIガイド

このページでは、Lakebase APIの概要、認証、利用可能なエンドポイント、REST API、Databricks CLI、Databricks SDK(Python、Java、Go)での一般的な運用パターンを紹介します。

操作およびパラメータの完全な一覧については 、Postgres APIリファレンスを参照してください。

注

一部の作業は ベータ版に残っています。 Postgres API参照は各操作の状態を示します。

Authentication

Lakebase APIは ワークスペースレベルのOAuth認証 を用いてプロジェクトインフラ管理(プロジェクト作成、設定設定の設定など)を行っています。

注

接続性は2種類あります。このAPIはプラットフォーム管理(プロジェクトの作成、ブランチの作成、コンピュート)用です。 データベース アクセスの場合 (クエリ データへの接続):

  • SQLクライアント (psql、pgAdmin、DBeaver):Lakebase OAuthトークンまたはPostgresのパスワードを使いましょう。 認証に関するページを参照してください。
  • データAPI (RESTful HTTP):Lakebase OAuthトークンを使用してください。 データ API を参照してください。
  • プログラミング言語のドライバ (psycopg、SQLAlchemy、JDBC):Lakebase OAuthトークンまたはPostgresのパスワードを使用してください。 クイック スタートを参照してください。

これら 2 つの認証レイヤーの詳細については、「 認証アーキテクチャ」を参照してください。

認証の設定

Databricks CLI を使用した認証:

databricks auth login --host https://your-workspace.cloud.databricks.com

ブラウザーのプロンプトに従ってログインします。 CLI は OAuth トークンを ~/.databricks/token-cache.jsonにキャッシュします。

次に、アクセス方法を選択します。

Python SDK

SDK は統合認証を使用し、OAuth トークンを自動的に処理します。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

SDK は統合認証を使用し、OAuth トークンを自動的に処理します。

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

コマンドでは、キャッシュされたトークンが自動的に使用されます。

databricks postgres list-projects

curl

トークンを生成し、ワークスペースのURLを直接API呼び出しに設定します。 Lakebaseのドキュメント全体に登場するカール例は、以下の2つの環境変数を前提としています。

export WORKSPACE="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "$WORKSPACE/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

OAuth トークンは 1 時間後に期限切れになります。 必要に応じて再生成します。

詳細については、「 OAuth を使用して Databricks へのユーザー アクセスを承認する」を参照してください。

使用可能なエンドポイント

Postgres API はベースパス /api/2.0/postgres/ を使用します。 コンピュートポリシーとリソース権限は別々のAPIパスを使用します。

サーバーレスコンピュートポリシー

Important

サーバーレス計算ポリシー Private Preview に登録されているワークスペースでは:

  • Lakebase プロジェクトを作成するには、Lakebase を許可するポリシーの CAN_USE または CAN_MANAGE が必要です。
  • 計算容量やスケール・トゥ・ゼロ設定を変更するには、Lakebase プロジェクト CAN_MANAGE を行い、そのポリシーを CAN_USE または CAN_MANAGE する必要があります。 これは、ポリシーが設定に制限を設けていない場合でも適用されます。
  • Lakebase プロジェクトの表示名を変更するには、Lakebase プロジェクトで必要なのは CAN_MANAGE のみです。
  • ポリシーを置き換えるには、Lakebaseプロジェクトに対する CAN_MANAGE と、両方のポリシーについて CAN_USE または CAN_MANAGE が必要です。 spec.compute_policy_idをクリアすると、デフォルトの Lakebase ポリシーが置き換え先として割り当てられます。

更新された設定は、ポリシーの現在の制約を満たし、必要なタグキー-値ペアを保持する必要があります。 設定変更の権限を参照してください。

プレビューアクセスをリクエストするには、Databricksアカウントチームにお問い合わせください。

ポリシーは計算容量やゼロにスケールするまでのアイドル時間を制限し、タグを強制できます。 ポリシー管理は API でのみ利用可能で、/api/2.0/policies/compute を使用して行います。

Lakebase プロジェクトを作成する際に、コンピュートポリシーを選択するには、spec.compute_policy_id を設定します。 ポリシー管理と権限については、「 サーバーレス計算ポリシーの管理」を参照してください。 Lakebase プロジェクト操作と計算更新を扱う Postgres API の例については、「 Lakebase プロジェクトでポリシーを使用する」を参照してください。 別個の spec.budget_policy_id フィールドはコスト帰属のための サーバーレス使用ポリシー を選択します。

添付したポリシーを変更するには、「 Lakebase プロジェクトのポリシーを置き換える」を参照してください。

プロジェクト

Operation メソッド エンドポイント Documentation
プロジェクトを作成 POST /projects プロジェクトの作成
プロジェクトを更新する PATCH /projects/{project_id} 一般設定
プロジェクトの削除 DELETE /projects/{project_id} プロジェクトを削除する
プロジェクトを取得する GET /projects/{project_id} プロジェクトの詳細を取得
プロジェクトを一覧表示する GET /projects プロジェクト一覧

ブランチ

Operation メソッド エンドポイント Documentation
ブランチの作成 POST /projects/{project_id}/branches 分岐を作成する
ブランチの更新 PATCH /projects/{project_id}/branches/{branch_id} ブランチ設定の更新
分岐の削除 DELETE /projects/{project_id}/branches/{branch_id} ブランチの削除
ブランチを取得する GET /projects/{project_id}/branches/{branch_id} ブランチの表示
ブランチを一覧表示する GET /projects/{project_id}/branches ブランチを一覧表示

スナップショット

Operation メソッド エンドポイント Documentation
スナップショットの作成 POST /projects/{project_id}/snapshots スナップショットを作成する
スナップショットの削除 DELETE /projects/{project_id}/snapshots/{snapshot_id} スナップショットの削除
スナップショットの取得 GET /projects/{project_id}/snapshots/{snapshot_id} スナップショットの取得とリスト
スナップショットを一覧表示する GET /projects/{project_id}/snapshots スナップショットの取得とリスト
スナップショットを復元(スナップショットから分岐を作成する) POST /projects/{project_id}/branches スナップショットから復元する

エンドポイント(コンピュートおよび読み取りレプリカ)

API では、コンピューティングは エンドポイントと呼ばれます。 概念の概要については、「 コンピューティングとエンドポイント」を参照してください。

次の表は、UI の概念を API の同等の概念にマップします。

UI の概念 API リソースまたはフィールド Documentation
プライマリ コンピューティング endpoint_type: ENDPOINT_TYPE_READ_WRITE が設定されたエンドポイント コンピューティングの管理
読み取りレプリカ endpoint_type: ENDPOINT_TYPE_READ_ONLY が設定されたエンドポイント リードレプリカの管理
高可用性 group エンドポイントスペックのフィールド (EndpointGroupSpec) 高可用性を管理
コンピューティング識別子 (UID、リソース名) エンドポイント オブジェクトの uid と name (完全なリソース パス) 識別子のコンピューティング

使用可能な操作

Operation メソッド エンドポイント Documentation
エンドポイントを作成する POST /projects/{project_id}/branches/{branch_id}/endpoints リードレプリカを作成する
エンドポイントの更新 PATCH /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} コンピュートを編集 / リードレプリカを編集 / 高可用性を管理する
エンドポイントを削除する DELETE /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} リードレプリカを削除してください
エンドポイントを取得する GET /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id} コンピューティングを表示する
エンドポイントを一覧表示する GET /projects/{project_id}/branches/{branch_id}/endpoints コンピューティングを表示する

読み書きエンドポイントは直接削除できません。 それらを削除するには、親ブランチを削除してください。 ブランチを維持しつつコンピューティング コストを避けるために、spec.disabled を true に設定します。 「 コンピュートを無効化または有効化する」を参照してください。

役割

Operation メソッド エンドポイント Documentation
ロールの一覧表示 GET /projects/{project_id}/branches/{branch_id}/roles Postgresのロールを見る
ロールの作成 POST /projects/{project_id}/branches/{branch_id}/roles OAuthロールを作成 | パスワードロールを作成
ロールを取得する GET /projects/{project_id}/branches/{branch_id}/roles/{role_id} Postgresのロールを見る
ロールの更新 PATCH /projects/{project_id}/branches/{branch_id}/roles/{role_id} ロールの更新
ロールの削除 DELETE /projects/{project_id}/branches/{branch_id}/roles/{role_id} ロールの削除

バックアップスケジュール

ルートブランチは単一のバックアップスケジュールを持ちます。 取得と更新のみ利用可能です。 更新により、スケジュールの頻度設定一式が置き換えられます。

Operation メソッド エンドポイント Documentation
バックアップスケジュールを用意しましょう GET /projects/{project_id}/branches/{branch_id}/snapshot-schedule バックアップスケジュールを作成しましょう
バックアップスケジュールの更新 PATCH /projects/{project_id}/branches/{branch_id}/snapshot-schedule バックアップスケジュールを作成しましょう

注

アップデートは長期にわたる作業です。 返された操作を done: true になるまでポーリングします。 実行時間の長い操作を参照してください。

カタログ

Operation メソッド エンドポイント Documentation
Unity カタログにデータベースを登録する POST /catalogs データベースの登録
カタログ登録を取得する GET /catalogs/{catalog_id} 登録状況を確認
カタログ登録の削除 DELETE /catalogs/{catalog_id} データベースの登録解除

注

登録と削除は実行時間の長い操作です。 返された操作を done: true になるまでポーリングします。 実行時間の長い操作を参照してください。

カタログ登録を削除しても、基になる Postgres データベースは削除されません。

同期テーブル

Operation メソッド エンドポイント Documentation
同期テーブルを作成する POST /synced_tables 同期テーブルの作成
同期されたテーブルを取得する GET /synced_tables/{table_name} 同期状況を確認する
同期されたテーブルを削除する DELETE /synced_tables/{table_name} 同期したテーブルを削除する

注

パス内の table_name は、 catalog.schema.table形式を使用します。

作成と削除は実行時間の長い操作です。 返された操作を done: true になるまでポーリングします。 実行時間の長い操作を参照してください。

同期されたテーブルを削除すると、Unity カタログの登録のみが削除されます。 Postgres テーブルを個別に削除して、領域を解放します。

変更データフィード

Lakebaseの変更データフィード (CDF)操作はブランチ単位です。 リクエストおよびレスポンスの詳細については、 Postgres APIリファレンスのCDF操作を参照してください。

Operation メソッド Documentation
CDF構成を作成する POST 変更データフィードを開始してください
CDFステータスを取得する GET 変更データフィードを開始してください
CDFのステータス一覧 GET 変更データフィードを開始してください
CDFの設定を入手してください GET 変更データフィードを開始してください
CDF構成を削除してください DELETE レイクベースのCDFを無効にする

注

変更データフィードを開始するためにCDF構成を作成します。 Lakebase UIからフィードを開始することもできます。 変更データ フィードの開始をご覧ください。

CDF構成を削除すると、その構成およびそのテーブルマッピングが永久に失われます。Unityカタログ内の宛先デルタテーブルは保持されます。

データベース認証情報

Operation メソッド エンドポイント Documentation
データベース資格情報を生成する POST /credentials OAuthトークン認証

運用

Operation メソッド エンドポイント Documentation
操作の取得 GET /projects/{project_id}/operations/{operation_id} 以下の例を参照してください

アクセス許可

Project の ACL アクセス許可は、 を使用し、/api/2.0/postgres/ ベース パスではありません。 request_object_typeをdatabase-projectsに設定し、プロジェクト ID (request_object_id など) にmy-appします。

Operation メソッド エンドポイント Documentation
プロジェクトのアクセス許可を取得する GET /api/2.0/permissions/database-projects/{project_id} 権限 API リファレンス
プロジェクトのアクセス許可を更新する PATCH /api/2.0/permissions/database-projects/{project_id} 権限 API リファレンス
プロジェクトのアクセス許可を置き換える PUT /api/2.0/permissions/database-projects/{project_id} 権限 API リファレンス

Lakebase プロジェクトの許可可能なアクセス許可レベルは、CAN_USE と CAN_MANAGE です。 CAN_CREATE は継承されたレベルであり、APIから設定することはできません。 アクセス 許可レベルを参照してください。

使用例と CLI/SDK/Terraform に相当するものについては、「 プログラムによるアクセス許可の付与」を参照してください。

オペレーションを取得

実行時間の長い操作の状態をリソース名で確認します。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)
print(f"Operation started: {operation.name()}")

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation (example: create project)
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

CLI

CLI は、既定で操作が完了するまで自動的に待機します。 --no-waitを使用してポーリングをスキップします。

# Create project without waiting
databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

# Later, check the operation status using the operation name from the response
databricks postgres get-operation projects/my-project/operations/<operation-id>

curl

# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

回答形式:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Project",
    "name": "projects/my-project",
    ...
  }
}

フィールド:

  • done:進行中はfalse、完了時はtrue
  • response: done が true のときの結果を含みます。
  • error: 操作失敗時のエラー詳細を含む

一般的なパターン

リソースの名前付け

リソースは階層的な名前付けパターンに従い、子リソースのスコープは親に依存します。

プロジェクトでは、次の形式が使用されます。

projects/{project_id}

操作などの子リソースは、親プロジェクトの下に階層化されます。

projects/{project_id}/operations/{operation_id}

つまり、操作やその他の子リソースにアクセスするには、親プロジェクト ID が必要です。

リソースID:

リソースを作成するときは、my-app、project_id、または branch_id パラメーターのリソース ID (endpoint_id など) を指定する必要があります。 この ID は、API 呼び出し ( projects/my-app/branches/development など) のリソース パスの一部になります。

role_id と database_id は API リソースを識別します。 spec.postgres_role と spec.postgres_database は、対応する Postgres オブジェクトの名前です。

必要に応じて display_name を指定して、リソースにわかりやすいラベルを付けることができます。 表示名を指定しない場合、システムは表示名としてリソース ID を使用します。

Tip

Lakebaseアプリでプロジェクトを探すには、プロジェクトリストの表示名を探してください。 プロジェクトの作成時にカスタム表示名を指定しなかった場合は、 project_id ("my-app" など) を検索します。

注

リソース ID は、作成後に変更できません。

要件:

  • 長さは 1 ~ 63 文字にする必要があります
  • 小文字、数字、ハイフンのみ
  • ハイフンで開始または終了することはできません
  • 例: my-app、 analytics-db、 customer-123

実行時間の長い操作 (LRO)

作成、更新、および削除操作は、完了状態を提供する databricks.longrunning.Operation オブジェクトを返します。

操作応答の例:

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

GetOperationを用いて完了するためのポーリング:

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

CLI

CLI は、既定で操作が完了するまで自動的に待機します。 --no-waitを使用してすぐに返します。

databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

curl

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'

doneがtrueされるまで、数秒ごとにポーリングします。

マスクを更新する

更新操作には、変更するフィールドを指定する update_mask パラメーターが必要です。 これにより、関連付けられていないフィールドが誤って上書きされるのを防ぐことができます。

フォーマットの違い:

メソッド Format Example
REST API Query parameter (クエリ パラメーター) ?update_mask=spec.display_name
Python SDK FieldMask オブジェクト update_mask=FieldMask(field_mask=["spec.display_name"])
CLI 位置指定引数 update-project NAME spec.display_name

エラー処理

Lakebase API は、標準の HTTP 状態コードを返します。

409: 競合する操作

Lakebase は、いくつかの理由で 409 Conflict エラーを返す場合があります。

  • プロジェクトで内部メンテナンス操作が進行中です。
  • プロジェクトは、同時操作の制限に達しました。
  • 独自の API 要求が重複しています。 たとえば、前のブランチの作成が完了する前にブランチを作成します。

意味:

Lakebase では、プロジェクトのメンテナンス操作をスケジュールすることがあります。 これらの操作のいずれかが進行中にクライアント要求が到着した場合、Lakebase は新しい要求を拒否し、 409 Conflict エラーが発生します。 また、プロジェクトが容量に入っているか、API 呼び出しが重複している場合にも、その応答が返される場合があります。

これは通常の動作です。 クライアントは、このエラーが発生したときに要求を再試行するように準備する必要があります。

すべきこと:

要求をやり直してください。 内部操作が完了するか容量が解放されると、Lakebase はプロジェクトの新しい要求を受け入れます。

再試行には指数バックオフを使用します。最初の再試行の前に短い間隔で待機してから、後続の各試行で待機を 2 倍にしてください。 開始間隔は 100 ミリ秒で、最大 30 秒は適切な既定値です。

Python SDK
import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.errors import ResourceConflict
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

def retry_on_conflict(fn, max_attempts=5, base_delay=0.1):
    """Retry a Lakebase API call when a conflicting operation is in progress."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except ResourceConflict:
            if attempt == max_attempts - 1:
                raise
            wait = base_delay * (2 ** attempt)
            print(f"Conflicting operation in progress. Retrying in {wait}s...")
            time.sleep(wait)

# Example: create a branch with retry
branch = retry_on_conflict(
    lambda: w.postgres.create_branch(
        parent="projects/my-project",
        branch=Branch(spec=BranchSpec(no_expiry=True)),
        branch_id="my-branch",
    ).wait()
)
curl
# Retry with exponential backoff on 409 responses
retry_on_conflict() {
  local cmd=("$@")
  local max_attempts=5
  local delay=0.1
  local attempt=0

  while [ $attempt -lt $max_attempts ]; do
    response=$(curl -s -w "\n%{http_code}" "${cmd[@]}")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -ne 409 ]; then
      echo "$body"
      return 0
    fi

    attempt=$((attempt + 1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Max retries reached. Last response: $body" >&2
      return 1
    fi

    echo "Conflicting operation in progress. Retrying in ${delay}s..." >&2
    sleep "$delay"
    delay=$((delay * 2))
  done
}

# Example: create a branch with retry
retry_on_conflict \
  -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=my-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"no_expiry": true}}'

注

Lakebase API 要求の 409 Conflict は、要求が適用されたのではなく、受け入れられなかったことを意味します。 対応する GET エンドポイントを呼び出して、再試行が成功した後は常にリソースの状態を確認します。

SDKとインフラストラクチャ・アズ・コード