LakebaseオートスケールAPIガイド

備考

Lakebaseオートスケールは、オートスケールコンピュート、ゼロへのスケール、分岐、即時復元を備えたLakebaseの最新バージョンです。 サポートされているリージョンについては、 「リージョンの提供状況」を参照してください。Lakebaseプロビジョニング ユーザーの場合は、 Lakebaseプロビジョニング」を参照してください。

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

完全な API リファレンスについては、 Postgres API ドキュメントを参照してください。

重要

Lakebase Postgres API は ベータ版 です。APIエンドポイント、問題、および動作は変更される可能性があります。

認証

Lakebase AutoscalingAPI 、プロジェクト インフラストラクチャの管理 (プロジェクトの作成、設定の構成など) に ワークスペース レベルの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

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

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

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

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

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

Bash

databricks postgres list-projects

curl

直接 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 へのユーザー アクセスを承認する」を参照してください。

利用可能なエンドポイント（ベータ版）

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

プロジェクト

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

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

APIでは、コンピュートを エンドポイント と呼びます。 UI とAPI用語の完全なマッピングについては、 「コンピュート」と「エンドポイント」を参照してください。

オペレーション	手法	エンドポイント	ドキュメント
エンドポイントを作成	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}	役割を削除する

カタログ

オペレーション	手法	エンドポイント	ドキュメント
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}	同期済みテーブルを削除する

注記

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

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

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

データベース資格情報

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

オペレーション

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

権限

プロジェクト ACL 権限では、 /api/2.0/postgres/ベース パスではなく、標準の Databricks 権限 APIが使用されます。request_object_typeをdatabase-projectsに設定し、 request_object_idプロジェクト ID に設定します。

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

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(...)
print(f"Operation started: {operation.name}")

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

Java SDK

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(...);
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を使用します:

Bash

# Create project without waiting
databricks postgres create-project --no-wait ...

# Later, check the operation status
databricks postgres get-operation projects/my-project/operations/abc123

curl

Bash

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

応答形式:

JSON

{
  "name": "projects/my-project/operations/abc123",
  "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 UI でプロジェクトを見つけるには、プロジェクト リストでその表示名を探します。プロジェクトの作成時にカスタム表示名を指定しなかった場合は、 project_id (「my-app」など) を検索します。

:::

注記

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

要件：

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

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

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

操作応答の例:

JSON

{
  "name": "projects/my-project/operations/abc123",
  "done": false
}

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

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(...)

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

Java SDK

Java

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

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(...);

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

CLI

デフォルトでは、CLI は操作が完了するまで自動的に待機します。すぐに戻るには--no-waitを使用します:

Bash

databricks postgres create-project --no-wait ...

curl

Bash

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/abc123" \
  -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

エラー処理

Lakebase APIは標準のHTTPステータスコードを返します。

409: 競合する操作

エラーメッセージ:

project already has running conflicting operations, scheduling of new ones is prohibited

その意味：

Lakebaseは、プロジェクトに関して社内メンテナンス作業をスケジュールすることがあります。これらの内部処理のいずれかが進行中にクライアントからのリクエストが届いた場合、Lakebase は新しいリクエストを409 Conflictエラーで拒否することができます。

これは想定される動作です。クライアントは、このエラーが発生した場合にリクエストを再試行する準備をしておく必要があります。

何をするか：

リクエストを再試行してください。内部処理が完了すると、Lakebaseは当該プロジェクトに関する新たな依頼を受け付けます。

再試行には指数バックオフを使用します。最初の再試行の前に短い間隔を待ち、その後は再試行ごとに待ち時間を2倍にします。開始間隔を100ミリ秒、最大間隔を30秒とするのが妥当なデフォルト値と言えるでしょう。

Python SDK

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

curl

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

SDK とInfrastructure-as-Code

• Python SDK
• Java SDK
• Go SDK
• 宣言型自動化バンドル
• バンドルでLakebaseプロジェクトを管理する
• Terraformプロバイダー
• Lakebase 向け Terraform を使い始める