Lakebase 用 Databricks CLI の使い始め方

Important

Lakebase 自動スケールは、 eastus、 eastus2、 centralus、 southcentralus、 westus、 westus2、 canadacentral、 brazilsouth、 northeurope、 uksouth、 westeurope、 australiaeast、 centralindia、 southeastasiaの各リージョンで使用できます。

Lakebase 自動スケールは、自動スケールコンピューティング、ゼロへのスケール、分岐、インスタントリストアを備えた最新バージョンの Lakebase です。 Lakebase プロビジョニング済みユーザーの場合は、「 Lakebase Provisioned」を参照してください。

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

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

[前提条件]

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

Databricks で認証する

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

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

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

注

複数のプロファイルがある場合は、 --profile フラグを使用して、使用するプロファイルを指定します: databricks postgres <command> --profile my-profile。構成済みのプロファイルを表示するには、 databricks auth profiles実行します。

その他の認証オプションについては、「 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 (たとえば、br-divine-sea-y2k942xa) を書き留めます。

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

export BRANCH_ID="br-divine-sea-y2k942xa"

br-divine-sea-y2k942xaを、リスト出力の実際の既定のブランチ ID に置き換えます。

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

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

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

name フィールドのエンドポイント ID をメモします。 projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}形式になります。エンドポイント ID ( ep-plain-sunset-y2vc0zan など) を抽出し、必要に応じて変数としてエクスポートします。

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

ep-plain-sunset-y2vc0zanを、リスト出力の実際のエンドポイント 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/br-divine-sea-y2k942xa",
      "no_expiry": true
    }
  }'

注

ブランチを作成するときは、有効期限ポリシーを指定する必要があります。 no_expiry: trueを使用して永続的ブランチを作成します。

JSON 仕様内でシェル変数 ( $PROJECT_ID や $BRANCH_IDなど) を使用するには、 --json 値に二重引用符を使用し、内部引用符をエスケープする必要があります。

機能ブランチには、データベース操作を許可する読み取り/書き込みコンピューティングエンドポイントが必要です。

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

機能ブランチでの開発とテストが完了したら、それを削除できます。

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 は操作の完了を待機します。 --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 ペイロードには、これらのフィールドの新しい値が含まれています。更新マスクに一覧表示されているフィールドのみが変更されます。

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-07