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 アカウントで認証するためのブラウザーウィンドウが開きます。

注

複数のプロファイルがある場合は、 --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 をメモします (たとえば、既定のブランチの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

このコマンドは、ブランチの現在の状態、保護状態、論理サイズ、ソースブランチの詳細 (該当する場合)、タイムスタンプを返します。

機能ブランチを作成する

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

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

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

注

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

ブランチの保護を更新する

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

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 get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

このコマンドは、エンドポイントの種類、自動スケール設定、現在の状態、接続ホスト、中断タイムアウト、タイムスタンプを返します。

読み取りレプリカを使用して読み取りをスケーリングする

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

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など) を持つ複数の読み取りレプリカを作成して、読み取りワークロードを分散できます。

自動スケールの制限を更新する

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

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

スケールをゼロに構成する

スケールをゼロに構成するには、更新マスクに spec.suspension を含めます。 suspend_timeout_duration（60～604800秒）を設定して非アクティブ時のタイムアウトを指定するか、no_suspension: true を設定して無効にします。両方を設定しないでください。 no_suspension: false設定が無効で、エラーが返されます。既定では、 production ブランチは 24 時間のタイムアウトでゼロにスケーリングされます。

# Disable scale to zero (compute stays active indefinitely)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "no_suspension": true
    }
  }'

# Enable scale to zero with a 5-minute inactivity timeout (60s–604800s)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "suspend_timeout_duration": "300s"
    }
  }'

ロールの管理

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

同期テーブルの管理

同期されたテーブルは、待機時間の短い運用読み取りのために、Unity カタログデータを Lakebase データベースにレプリケートします。 {catalog}.{schema}.{table} ID を持つ create-synced-table を使用します。

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "databricks_postgres",
      "create_database_objects_if_missing": true
    }
  }'

同期されたテーブル ID は、Unity カタログエンティティ名になり、Postgres テーブルを識別します。状態を取得し、同じ ID 形式で同期されたテーブルを削除します。

# Check status
databricks postgres get-synced-table "synced_tables/my-catalog.sales.orders"

# Delete
databricks postgres delete-synced-table "synced_tables/my-catalog.sales.orders"

create-synced-table と create-catalog は実行時間の長い操作です。既定では、CLI は完了を待機します。 --no-waitを使用してすぐに返すか、--timeoutを使用してカスタム待機時間を設定します。実行時間の長い操作を参照してください。

同期モード、データ型マッピング、容量計画に関する詳細なガイダンスについては、「同期されたテーブルを使用して Lakehouse データを提供する」を参照してください。

主要な概念を理解する

長時間実行される操作

作成、更新、削除の各コマンドは、実行時間の長い操作です。既定では、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-06-24

Lakebase 用 Databricks CLI の使い始め方

[前提条件]

Azure Databricksで認証する

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

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

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

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

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

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

プロジェクトの管理

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

プロジェクトの詳細を取得する

ブランチを管理する

ブランチの詳細を取得する

機能ブランチを作成する

ブランチの保護を更新する

コンピューティングの管理

コンピューティングの詳細を取得する

読み取りレプリカを使用して読み取りをスケーリングする

自動スケールの制限を更新する

スケールをゼロに構成する

ロールの管理

ロールの作成

ロールを一覧表示して取得する

ロールを更新する

ロールを削除する

同期テーブルの管理

主要な概念を理解する

長時間実行される操作

リソースの名前付け

マスクを更新する

その他のリソース

フィードバック

その他のリソース

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