Lakebase 自動スケール API ガイド

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

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

Authentication

Lakebase 自動スケール API では、プロジェクト インフラストラクチャの管理 (プロジェクトの作成、設定の構成など) に ワークスペース レベルの OAuth 認証 が使用されます。

認証を設定する

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

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

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/を使用します。

プロジェクト

ブランチ

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

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

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

使用可能な操作

役割

カタログ

同期されたテーブル

データベース資格情報

操作

アクセス許可

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

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

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

Get 操作

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

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 など) のリソース パスの一部になります。

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

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

Lakebase UI でプロジェクトを見つけるには、プロジェクトの一覧でその表示名を探します。 プロジェクトの作成時にカスタム表示名を指定しなかった場合は、 project_id ("my-app" など) を検索します。

:::

Requirements:

• 長さは 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 パラメーターが必要です。 これにより、関連付けられていないフィールドが誤って上書きされるのを防ぐことができます。

形式の違い:

エラー処理

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}}'

SDK とコードとしてのインフラストラクチャ

• Python SDK
• Java SDK
• Go SDK
• 宣言型オートメーション バンドル
• バンドルを使用して Lakebase プロジェクトを管理する
• Terraform プロバイダー
• Terraform for Lakebase の概要