Lakebase 用の Databricks CLI を使い始める

備考

Lakebase オートスケールは次のリージョンで利用できます: us-east-1 、 us-east-2 、 eu-central-1 、 eu-west-1 、 eu-west-2 、 ap-south-1 、 ap-southeast-1 、 ap-southeast-2 。

Lakebase オートスケールは、オートスケールコンピュート、ゼロへのスケール、分岐、即時復元を備えた Lakebase の最新バージョンです。 Lakebase プロビジョニングとの機能の比較については、「バージョン間の選択」を参照してください。

このガイドは、 Databricks CLIを使用して Lakebase プロジェクト、ブランチ、コンピュート (エンドポイント) を管理する方法を開始するのに役立ちます。わずか数個のコマンドで実用的なプロジェクトを作成する方法を学びます。

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

前提条件

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

Databricksで認証する

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

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

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

注記

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

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

コマンドヘルプを取得する

CLI はすべてのコマンドに組み込みヘルプを提供します。使用可能なコマンドとオプションを表示するには、 --helpを使用します。

すべての Postgres コマンドの概要を取得します。

Bash
databricks postgres --help

これにより、使用可能なすべてのコマンド、グローバルフラグ、およびリソースの命名規則に関する情報が表示されます。

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

Bash
databricks postgres create-project --help

これには、コマンドの目的、必須およびオプション、使用例、および使用可能なフラグが表示されます。

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

次のステップに従って、ブランチとコンピュートエンドポイントを含む完全な作業プロジェクトを作成します。

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

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

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

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

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

Bash
export PROJECT_ID="my-project"

2. 支店IDを取得する

デフォルトのブランチ ID を見つけるには、プロジェクト内のブランチを一覧表示します。

Bash
databricks postgres list-branches projects/$PROJECT_ID

これは、プロジェクト内のすべてのブランチに関する情報を返します。ステータスが"default": trueのブランチを探します。nameフィールドのブランチ ID (例: br-divine-sea-y2k942xa ) をメモします。

オプションで、後続のコマンドで使用するためにブランチ ID を変数としてエクスポートします。

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

br-divine-sea-y2k942xa 、リスト出力の実際のデフォルトのブランチ ID に置き換えます。

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

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

Bash
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 ) を抽出し、オプションで変数としてエクスポートします。

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

ep-plain-sunset-y2vc0zanリスト出力の実際のエンドポイント ID に置き換えます。

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

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

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

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

リソースの管理

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

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

Bash
databricks postgres list-projects

これにより、各プロジェクトの名前、表示名、現在の状態、作成/更新のタイムスタンプなどの情報が返されます。

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

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

Bash
databricks postgres get-project projects/$PROJECT_ID

これにより、表示名、PostgreSQL バージョン、所有者、履歴保持期間、ブランチサイズの制限、デフォルトのエンドポイント設定、ストレージサイズ、作成/更新のタイムスタンプなどの詳細なプロジェクト構成が返されます。

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

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

これにより、現在の状態、デフォルトのブランチステータス、保護ステータス、論理サイズ、ソースブランチの詳細 (別のブランチから分岐した場合)、作成/更新のタイムスタンプなどの詳細なブランチ情報が返されます。

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

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

これにより、エンドポイントのタイプ (読み取り/書き込みまたは読み取り専用)、オートスケール設定 (最小および最大コンピュート単位)、現在の状態 (ACTIVE、IDLE など)、接続ホスト、サスペンドタイムアウト、および作成/更新タイムスタンプを含む詳細なエンドポイント構成が返されます。

リソースを更新する

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

Bash
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タイムスタンプを示す更新されたリソースを返します。

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

Bash
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 を実際の値に置き換えます。

Bash
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値に二重引用符を使用し、内部の引用符をエスケープする必要があります。

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

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

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

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

注記

削除コマンドはすぐに戻りますが、実際の削除が完了するまでには時間がかかる場合があります。対応するリソース取得コマンドを実行することで削除を確認できます。リソースが完全に削除されるとエラーが返されます。

リードレプリカで読み取りをスケールする

増加した読み取りトラフィックを処理するために読み取りレプリカを追加します。この例では、リードレプリカをまだ本番運用ブランチに追加します。

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

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

操作ステータスをポーリングします。

Bash
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で認証する​

コマンドヘルプを取得する​

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

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

2. 支店IDを取得する​

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

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

リソースの管理​

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

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

リソースを更新する​

一般的なワークフロー​

本番運用から機能ブランチを作成する​

リードレプリカで読み取りをスケールする​

重要な概念を理解する​

長時間実行される操作​

リソースの命名​

マスクを更新する​

次のステップ​