Lakebase 用 Databricks CLI の使い始め方

このガイドは、Databricks CLI を使用して、Lakebase プロジェクト、ブランチ、コンピューティング (エンドポイント) を管理する際に役立ちます。 いくつかのコマンドで作業プロジェクトを作成する方法について説明します。

完全なコマンド リファレンスと使用可能なすべてのオプションについては、 Databricks CLI postgres コマンドを参照してください。

[前提条件]

• Databricks CLI: Databricks CLI をインストールします。 Databricks CLI のインストールを参照してください。
• ワークスペース へのアクセス: Lakebase リソースが存在する Azure Databricks ワークスペースにアクセスできる必要があります。

Azure Databricksで認証する

CLI コマンドを実行する前に、Azure Databricks ワークスペースで認証します。

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

https://your-workspace.cloud.databricks.comを実際のワークスペース URL に置き換えます。 このコマンドを実行すると、OAuth を使用して Azure Databricks アカウントで認証するためのブラウザー ウィンドウが開きます。

その他の認証オプションについては、「 Databricks 認証」を参照してください。

コマンドのヘルプを表示する

CLI には、すべてのコマンドに組み込みのヘルプが用意されています。 --helpを使用して、使用可能なコマンドとオプションを確認します。

すべての Postgres コマンドの概要を確認します。

databricks postgres --help

このコマンドは、使用可能なすべてのコマンド、グローバル フラグ、およびリソースの名前付け規則に関する情報を表示します。

特定のコマンドの詳細なヘルプを表示します。

databricks postgres create-project --help

これは、コマンドの目的、必須パラメーターと省略可能なパラメーター、使用例、および使用可能なフラグを示しています。

クイック スタート: 最初のプロジェクトを作成する

ブランチとコンピューティング エンドポイントを使用して完全な作業プロジェクトを作成するには、次の手順に従います。

1. プロジェクトを作成する

Lakebase プロジェクトを作成します。

databricks postgres create-project my-project \
  --json '{
    "spec": {
      "display_name": "My Lakebase Project"
    }
  }'

このコマンドはプロジェクトを作成し、プロジェクトが完了するまで待機します。 プロジェクト ID (my-project) は、リソース名 ( projects/my-project) の一部になります。 プロジェクトは、既定の運用ブランチと読み取り/書き込みコンピューティング エンドポイントを使用して作成されます。どちらも自動生成された ID を使用します。

必要に応じて、後続のコマンドで使用する変数としてプロジェクト ID をエクスポートします。

export PROJECT_ID="my-project"

2. ブランチ ID を取得する

プロジェクト内のブランチを一覧表示して、既定のブランチ ID を見つけます。

databricks postgres list-branches projects/$PROJECT_ID

これにより、プロジェクト内のすべてのブランチに関する情報が返されます。 状態に "default": true があるブランチを探します。 name フィールドのブランチ ID をメモします (たとえば、既定のブランチのproduction)。

必要に応じて、後続のコマンドで使用する変数としてブランチ ID をエクスポートします。

export BRANCH_ID="production"

productionを、リスト出力の実際のブランチ ID に置き換えます。

3. エンドポイント ID を取得する

ブランチ内のエンドポイントを一覧表示します。 既定のブランチには、読み取り/書き込みエンドポイントが自動的に含まれます。

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

name フィールドのエンドポイント ID をメモします (たとえば、既定の読み取り/書き込みエンドポイントのprimary)。 必要に応じて、変数としてエクスポートします。

export ENDPOINT_ID="primary"

primaryを、リスト出力の実際のエンドポイント ID に置き換えます。

4. データベース資格情報を生成する

データベースに接続するための資格情報を生成します。

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

このコマンドは、Databricks ID を使用してデータにアクセスするために psql などの PostgreSQL クライアントで使用できる OAuth トークンを返します。 psql を使用した接続の詳細な手順については、「 psql を使用した接続」を参照してください。 トークンの有効期限と認証の詳細については、「 認証」を参照してください。

リソースの管理

すべてのプロジェクトを一覧表示する

ワークスペース内のすべてのプロジェクトを一覧表示します。

databricks postgres list-projects

このコマンドは、名前、表示名、現在の状態など、各プロジェクトに関する情報を返します。 また、タイムスタンプの作成と更新も含まれます。

リソースの詳細を取得する

プロジェクトに関する詳細情報を取得します。

databricks postgres get-project projects/$PROJECT_ID

このコマンドは、表示名、PostgreSQL のバージョン、所有者、履歴の保持期間など、詳細なプロジェクト構成を返します。 また、ブランチ サイズの制限、既定のエンドポイント設定、ストレージ サイズ、作成と更新のタイムスタンプも含まれます。

ブランチに関する詳細情報を取得する。

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

このコマンドは、現在の状態、既定のブランチの状態、保護の状態、論理サイズなど、詳細なブランチ情報を返します。 また、ソース ブランチの詳細 (別のブランチから分岐している場合) や、タイムスタンプの作成と更新も含まれます。

エンドポイントに関する詳細情報を取得します。

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

このコマンドは、エンドポイントの種類 (読み取り/書き込みまたは読み取り専用)、自動スケール設定 (最小および最大コンピューティング ユニット)、現在の状態 (ACTIVE、IDLE など) など、詳細なエンドポイント構成を返します。 また、接続ホスト、一時停止タイムアウト、作成と更新のタイムスタンプも含まれます。

リソースの更新

更新マスク パターンを使用してリソースを更新します。 更新マスクは、更新するフィールドを指定します。

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

次の使用例は、 spec.is_protected を true に設定し、ブランチを保護します。 更新マスク (spec.is_protected) は、更新するフィールドを API に指示します。 このコマンドは、新しい値と更新された update_time タイムスタンプを示す更新されたリソースを返します。

複数のフィールドを更新するには、コンマ区切りのリストを使用します。

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

一般的なワークフロー

運用環境から機能ブランチを作成する

既存のブランチに基づいて新しいブランチを作成し、変更をテストします。 source_branchを指定すると、新しいブランチは作成時にソース ブランチと同じスキーマとデータを持ちます。 プロジェクト ID と分岐 ID を実際の値に置き換えます。

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/production",
      "no_expiry": true
    }
  }'

Lakebase は、プライマリの読み取り/書き込みコンピューティング エンドポイントを使用して、機能ブランチを自動的に作成します。 機能ブランチでの開発とテストが完了したら、それを削除できます。

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

読み取りレプリカを使って読み取りをスケールする

読み取りレプリカを追加して、読み取りトラフィックの増加を処理します。 次の例では、既定の運用ブランチに読み取りレプリカを追加します。

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

異なるエンドポイント ID (read-replica-1、 read-replica-2など) を持つ複数の読み取りレプリカを作成して、読み取りワークロードを分散できます。

ロールの管理

CLI を使用して、ブランチ内のデータベース アクセス用の Postgres ロールを作成および管理します。 ロールの種類と認証の詳細なガイダンスについては、「 Postgres ロールの作成」を参照してください。

ロールの作成

パスワードベースのロールを作成します。

databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

Azure Databricks ID に関連付けられた OAuth ロールを作成します。

# For a user:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

# For a service principal:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<sp-client-id>"}}'

ロールの一覧表示と取得

ブランチ内のすべてのロールを一覧表示します。

databricks postgres list-roles projects/$PROJECT_ID/branches/$BRANCH_ID

特定のロールに関する詳細を取得します。

databricks postgres get-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

応答には、更新呼び出しと削除呼び出しに必要なシステム生成ロール リソース名 ( rol-xxxx-xxxxxxxxxx など) が含まれます。

ロールを更新する

更新マスク パターンを使用してロールを更新します。 更新マスクを 2 番目の位置引数として渡します。

spec.attributes更新するときは、3 つの属性フィールドをすべて指定する必要があります。API は属性オブジェクト全体を置き換えます。

databricks postgres update-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  "spec.attributes" \
  --json '{"spec": {"attributes": {"createdb": true, "createrole": false, "bypassrls": false}}}'

ロールを削除する

databricks postgres delete-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

ロールがデータベース オブジェクトを所有している場合は、削除前に --reassign-owned-to を使用して所有権を譲渡します。

databricks postgres delete-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  --reassign-owned-to projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$OTHER_ROLE_ID

主要な概念を理解する

長時間実行される操作

作成、更新、削除の各コマンドは、実行時間の長い操作です。 既定では、CLI は操作の完了を待機します。 --no-waitを使用してすぐに戻り、状態を個別にポーリングします。

databricks postgres create-project $PROJECT_ID \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

操作状況を監視します。

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

リソースの名前付け

Lakebase では、階層型リソース名が使用されます。

• プロジェクト: projects/{project_id}。 プロジェクトの作成時にプロジェクト ID を指定します。
• 分岐: projects/{project_id}/branches/{branch_id}。 ブランチ ID は、ブランチの作成時に指定します。
• エンドポイント: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}。 エンドポイントの作成時に、エンドポイント ID ( primary や read-replica-1など) を指定します。

ID の長さは 1 ~ 63 文字で、小文字で始まり、小文字、数字、ハイフンのみを含める必要があります。

マスクを更新する

更新コマンドには、変更するフィールドを指定する更新マスクが必要です。 マスクは、 spec.display_name のようなフィールド パスか、複数のフィールドのコンマ区切りリストです。

--json ペイロードには、これらのフィールドの新しい値が含まれています。 更新マスクに一覧表示されているフィールドのみが変更されます。

次のステップ

• Databricks CLI postgres コマンド参照
• Postgres ロールを作成する
• psql を使用して接続する
• ブランチを管理する
• 自動スケールの構成