Lakebase APIガイド

このページでは、認証、利用可能なEndpoint、 REST API 、 Databricks CLI 、および Databricks SDK ( Python 、 Java 、Go) を操作するための一般的なパターンなど、Lakebase API の概要について説明します。

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

注記

一部の操作は Beta のままです。Postgres API リファレンスには、各操作のステータスが記載されています。

認証

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 を使用して認証します。

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

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

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

Python SDK
Java SDK
CLI
curl

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

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

Java
import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

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

Bash
databricks postgres list-projects

直接 API 呼び出し用のトークンを生成します。

Bash
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "https://your-workspace.cloud.databricks.com/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

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

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

利用可能なEndpoint

すべてのエンドポイントは基本パス/api/2.0/postgres/を使用します。

プロジェクト

オペレーション	手法	エンドポイント	ドキュメント
プロジェクトを作成	`POST`	`/projects`	プロジェクトを作成する
プロジェクトを更新	`PATCH`	`/projects/{project_id}`	一般設定
プロジェクトを削除	`DELETE`	`/projects/{project_id}`	プロジェクトを削除する
プロジェクトを取得	`GET`	`/projects/{project_id}`	プロジェクトの詳細を取得する
プロジェクトの一覧	`GET`	`/projects`	プロジェクトの一覧

オペレーション	手法	エンドポイント	ドキュメント
プロジェクトを作成	`POST`	`/projects`	プロジェクトを作成する
プロジェクトを更新	`PATCH`	`/projects/{project_id}`	一般設定
プロジェクトを削除	`DELETE`	`/projects/{project_id}`	プロジェクトを削除する
プロジェクトを取得	`GET`	`/projects/{project_id}`	プロジェクトの詳細を取得する
プロジェクトの一覧	`GET`	`/projects`	プロジェクトの一覧

ブランチ

オペレーション	手法	エンドポイント	ドキュメント
ブランチを作成	`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`	ブランチを一覧表示する

オペレーション	手法	エンドポイント	ドキュメント
ブランチを作成	`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`	ブランチを一覧表示する

エンドポイント (コンピュートとリードレプリカ)

APIでは、コンピュートを エンドポイント と呼びます。概念的な概要については、「コンピュートとエンドポイント」を参照してください。

以下の表は、UIの概念とそれに対応するAPIの概念を対応付けたものです。

UIコンセプト	APIリソースまたはフィールド	ドキュメント
プライマリコンピュート	エンドポイント `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	コンピュートの管理
レプリカを読む	エンドポイント `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	リードレプリカを管理する
高可用性	`group` エンドポイント仕様のフィールド（ `EndpointGroupSpec` ）	高可用性を管理する
コンピュート識別子 ( UID 、リソース名)	`uid` Endpoint オブジェクト上の`name` (完全なリソースパス)	コンピュート識別子

UIコンセプト	APIリソースまたはフィールド	ドキュメント
プライマリコンピュート	エンドポイント `endpoint_type: ENDPOINT_TYPE_READ_WRITE`	コンピュートの管理
レプリカを読む	エンドポイント `endpoint_type: ENDPOINT_TYPE_READ_ONLY`	リードレプリカを管理する
高可用性	`group` エンドポイント仕様のフィールド（ `EndpointGroupSpec` ）	高可用性を管理する
コンピュート識別子 ( UID 、リソース名)	`uid` Endpoint オブジェクト上の`name` (完全なリソースパス)	コンピュート識別子

利用可能な操作

オペレーション	手法	エンドポイント	ドキュメント
エンドポイントを作成	`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`	コンピュートを見る

オペレーション	手法	エンドポイント	ドキュメント
エンドポイントを作成	`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`	コンピュートを見る

役割

オペレーション	手法	エンドポイント	ドキュメント
役割をリストする	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Postgres のロールを表示
CREATEROLE	`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}`	役割を削除する

オペレーション	手法	エンドポイント	ドキュメント
役割をリストする	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	Postgres のロールを表示
CREATEROLE	`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}`	役割を削除する

カタログ

オペレーション	手法	エンドポイント	ドキュメント
Unity Catalogでデータベースを登録する	`POST`	`/catalogs`	データベースを登録する
カタログ登録を取得する	`GET`	`/catalogs/{catalog_id}`	登録状況を確認する
カタログ登録を削除する	`DELETE`	`/catalogs/{catalog_id}`	データベースの登録を解除する

オペレーション	手法	エンドポイント	ドキュメント
Unity Catalogでデータベースを登録する	`POST`	`/catalogs`	データベースを登録する
カタログ登録を取得する	`GET`	`/catalogs/{catalog_id}`	登録状況を確認する
カタログ登録を削除する	`DELETE`	`/catalogs/{catalog_id}`	データベースの登録を解除する

注記

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

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

同期されたテーブル

オペレーション	手法	エンドポイント	ドキュメント
同期テーブルを作成する	`POST`	`/synced_tables`	同期テーブルを作成する
同期されたテーブルを取得	`GET`	`/synced_tables/{table_name}`	同期ステータスを確認する
同期テーブルを削除	`DELETE`	`/synced_tables/{table_name}`	同期済みテーブルを削除する

オペレーション	手法	エンドポイント	ドキュメント
同期テーブルを作成する	`POST`	`/synced_tables`	同期テーブルを作成する
同期されたテーブルを取得	`GET`	`/synced_tables/{table_name}`	同期ステータスを確認する
同期テーブルを削除	`DELETE`	`/synced_tables/{table_name}`	同期済みテーブルを削除する

注記

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

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

同期されたテーブルを削除しても、 Unity Catalog登録情報のみが削除されます。空き容量を確保するために、Postgresテーブルを個別に削除してください。

チェンジデータフィード

Lakebase チェンジデータフィード (CDF) 操作は、Branch にスコープされます。リクエストとレスポンスの詳細については、Postgres API リファレンスのチェンジデータフィード操作を参照してください。

オペレーション	手法	ドキュメント
チェンジデータフィード設定を作成	`POST`	チェンジデータフィードを起動してください
チェンジデータフィードのステータスを取得	`GET`	チェンジデータフィードを起動してください
チェンジデータフィードのステータスを一覧表示	`GET`	チェンジデータフィードを起動してください
チェンジデータフィード設定を取得	`GET`	チェンジデータフィードを起動してください
チェンジデータフィード設定を削除	`DELETE`	Lakebase チェンジデータフィードを無効化

オペレーション	手法	ドキュメント
チェンジデータフィード設定を作成	`POST`	チェンジデータフィードを起動してください
チェンジデータフィードのステータスを取得	`GET`	チェンジデータフィードを起動してください
チェンジデータフィードのステータスを一覧表示	`GET`	チェンジデータフィードを起動してください
チェンジデータフィード設定を取得	`GET`	チェンジデータフィードを起動してください
チェンジデータフィード設定を削除	`DELETE`	Lakebase チェンジデータフィードを無効化

注記

チェンジデータフィードを起動するには、チェンジデータフィード設定を作成します。Lakebase UI からフィードを起動することもできます。チェンジデータフィードの起動を参照してください。

チェンジデータフィード設定を削除すると、その設定とテーブルマッピングが完全に削除されます。Unity Catalog 内の配信先 Delta テーブルは保持されます。

データベース資格情報

オペレーション	手法	エンドポイント	ドキュメント
データベース資格情報を生成する	`POST`	`/credentials`	OAuth認証

オペレーション

オペレーション	手法	エンドポイント	ドキュメント
取得操作	`GET`	`/projects/{project_id}/operations/{operation_id}`	以下の例を参照してください

権限

プロジェクト ACL の権限は、 /api/2.0/postgres/ベースパスではなく、標準の Databricks Permissions APIを使用します。request_object_typeをdatabase-projectsに、 request_object_idプロジェクト ID に設定してください (例: my-app )。

オペレーション	手法	エンドポイント	ドキュメント
プロジェクトの権限を取得する	`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リファレンス

オペレーション	手法	エンドポイント	ドキュメント
プロジェクトの権限を取得する	`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
Java SDK
CLI
curl

Python
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
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 は操作が完了するまで自動的に待機します。ポーリングをスキップするには--no-waitを使用します:

Bash
# 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>

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

応答形式:

JSON
{
  "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:

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

オプションでdisplay_nameを指定して、リソースにさらに説明的なラベルを付けることもできます。表示名を指定しない場合は、システムはリソース ID を表示名として使用します。

:::tip UI でリソースを見つける

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

:::

注記

リソース ID は作成後に変更することはできません。

要件：

1～63文字で入力してください
小文字、数字、ハイフンのみ
ハイフンで始まったり終わったりすることはできません
例: my-app 、 analytics-db 、 customer-123

長期実行オペレーション（LRO）

作成、更新、および削除操作では、完了ステータスを提供するdatabricks.longrunning.Operationオブジェクトが返されます。

操作応答の例:

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

GetOperation を使用して完了をポーリングします。

Python SDK
Java SDK
CLI
curl

Python
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
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 は操作が完了するまで自動的に待機します。すぐに戻るには--no-waitを使用します:

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

Bash
# 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問題が必要です。これにより、関係のないフィールドが誤って上書きされることがなくなります。

フォーマットの違い:

手法	フォーマット	例
REST API	クエリー	`?update_mask=spec.display_name`
Python SDK	FieldMaskオブジェクト	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	位置的議論	`update-project NAME spec.display_name`

手法	フォーマット	例
REST API	クエリー	`?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
curl

Python
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()
)

Bash
# 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エンドポイントを呼び出して、必ずリソースの状態を確認してください。

認証​

認証を設定する​

利用可能なEndpoint​

プロジェクト​

ブランチ​

エンドポイント (コンピュートとリードレプリカ)​

利用可能な操作​

役割​

カタログ​

同期されたテーブル​

チェンジデータフィード​

データベース資格情報​

オペレーション​

権限​

取得操作​

一般的なパターン​

リソースの命名​

長期実行オペレーション（LRO）​

マスクを更新する​

エラー処理​

409: 競合する操作​

SDK とInfrastructure-as-Code​

認証