メインコンテンツまでスキップ
に最終更新

Lakebase 用の Databricks CLI を使い始める

このガイドは、 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 をメモしてください (例えば、デフォルト ブランチの場合はproduction )。

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

Bash
export BRANCH_ID="production"

productionリスト出力から実際の支店IDに置き換えてください。

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

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

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

nameフィールドのエンドポイント ID をメモしてください (たとえば、デフォルトの読み書きエンドポイントの場合はprimary )。必要に応じて変数としてエクスポートします。

Bash
export ENDPOINT_ID="primary"

primaryリスト出力の実際のエンドポイント 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/production",
      "no_expiry": true
    }
  }'
注記

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

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

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

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

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

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

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

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

役割を作成する​

パスワードベースのロールを作成する：

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

Databricks IDに紐づいたOAuthロールを作成します。

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

役割の一覧と取得​

ブランチ内のすべての役割を一覧表示します。

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

特定の役割に関する詳細情報を取得する：

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

応答には、更新および削除呼び出しに必要な、システムによって生成されたロールリソース名（例： rol-xxxx-xxxxxxxxxx ）が含まれます。

役割を更新する​

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

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

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

役割を削除する​

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

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

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

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ペイロードには、これらのフィールドの新しい値が含まれます。更新マスクにリストされているフィールドのみが変更されます。

次のステップ​

このページの見出し