databricks-lakebase

Lakebase Postgres Autoscaling

最初に：CLI の基本、認証、プロファイルの選択については、親の databricks-core スキルを使用してください。

Lakebase は、AWS と Azure の両方で利用できる（GA）Databricks のサーバーレス Postgres 互換データベースです。自動スケーリング、ブランチ機能、ゼロへのスケールを備えた、完全マネージドの OLTP ストレージを提供します。

Provisioned Lakebase はすでに存在しません。絶対に作成しないでください。 旧 Provisioned ティア（静的でスケーリングできない Postgres。databricks database CLI／w.database SDK）は、2026 年夏に Autoscaling へ移行されます。お客様による操作は不要です。現在の Lakebase は Autoscaling のみです（databricks postgres／w.postgres）。Provisioned インスタンスを作成しようとしないでください。ユーザーから依頼された場合は、Provisioned インスタンスはすでに存在しないことを伝え、Autoscaling を案内してください。アプリ設定にあるレガシーの database リソースキーは廃止扱いとし、postgres リソースキーに移行してください。レガシー DAB の synced_database_tables リソースについては、代わりに databricks postgres create-synced-table CLI フローを使用してください（Common Issues の行と references/synced-tables.md を参照）。

古い設定やドキュメントを読む際の参考として、廃止された Provisioned ティアと Autoscaling の対応関係を以下に示します。

項目	Provisioned（廃止）	Autoscaling（現在）
CLI グループ	databricks database	databricks postgres
最上位リソース	インスタンス	プロジェクト
容量	CU_1–CU_8（16 GB/CU）	0.5–112 CU（2 GB/CU）
ブランチ機能	非対応	フルサポート
ゼロへのスケール	非対応	設定可能
HA	読み取り可能なセカンダリ	1～3 個のセカンダリ＋読み取りレプリカ
Data API	利用不可	PostgREST HTTP API
クラウド	AWS のみ	AWS と Azure

コンプライアンス： HIPAA、C5、TISAX、または None に対応しています。

機能

• プロジェクトのライフサイクル -- Lakebase Postgres Autoscaling プロジェクトの作成、更新、削除
• ブランチ機能 -- TTL、ポイントインタイムリカバリ、リセットに対応したコピーオンライト方式のブランチ
• コンピュートのスケーリング -- 0.5～32 CU の自動スケーリング、36～112 CU の固定容量、ゼロへのスケール
• 高可用性 -- プライマリ 1 台＋セカンダリ 1～3 台、自動フェイルオーバー
• PostgreSQL 接続 -- OAuth トークンの更新、コネクションプーリング、SSL
• Data API -- PostgREST 互換の HTTP CRUD（Autoscaling のみ）
• Lakebase 同期テーブル -- Unity Catalog の Delta テーブルを Postgres に同期（以前は Reverse ETL と呼ばれていました）
• Databricks App との統合 -- Lakebase 機能を使ったアプリのひな形を作成し、デプロイを先に行うワークフロー
• クラウドサポート -- AWS と Azure（GA）

リファレンスドキュメント：

• computes-and-scaling.md — サイズ設定、エンドポイント管理、ゼロへのスケール、HA
• connectivity.md — 接続パターン、トークンの更新、Data API
• synced-tables.md — Lakebase 同期テーブル、データ型のマッピング、容量計画
• lakehouse-sync.md — Lakebase Postgres から Unity Catalog の Delta テーブルへの CDC（databricks postgres *-cdf-config／w.postgres.*_cdf_config でプログラムから設定可能、Beta）
• pgvector.md — pgvector 拡張機能によるベクトル類似検索
• off-platform.md — オフプラットフォームの Lakebase（Databricks Apps ではありません）：@databricks/lakebase を使用して接続する外部 Node.js アプリ、環境変数の管理、トークンの更新、Drizzle ORM

リソース階層

Project (top-level container)
  └── Branch (isolated database environment, copy-on-write)
        ├── Endpoint (read-write or read-only)
        ├── Database (standard Postgres DB)
        └── Role (Postgres role)

• プロジェクト：最上位のコンテナです。作成すると、production ブランチと primary 読み書きエンドポイントが自動的にプロビジョニングされます。
• ブランチ：親とストレージを共有する分離されたデータベース環境です（コピーオンライト方式）。状態：READY、ARCHIVED。
• エンドポイント（UI では Compute と呼ばれます）：ブランチを稼働させるコンピュートリソースです。タイプ：ENDPOINT_TYPE_READ_WRITE、ENDPOINT_TYPE_READ_ONLY。
• データベース：ブランチ内の標準 Postgres データベースです。デフォルト：databricks_postgres。
• ロール：ブランチ内の Postgres ロールです。

リソース名の形式

リソース	形式
プロジェクト	projects/{project_id}
ブランチ	projects/{project_id}/branches/{branch_id}
エンドポイント	projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}
データベース	projects/{project_id}/branches/{branch_id}/databases/{database_id}

すべての ID は1～63文字で、小文字のアルファベットで始まり、小文字のアルファベット、数字、ハイフンのみを使用します（RFC 1123）。

CLI の検出 -- 必ず最初に実行してください

注：「Lakebase」は製品名で、CLI のコマンドグループは postgres です。すべてのコマンドで databricks postgres ... を使用します。

コマンド構文を推測しないでください。 次のように、利用可能なコマンドを動的に検出してください。

databricks postgres -h                    # List all subcommands
databricks postgres <subcommand> -h       # Flags, args, JSON fields

プロジェクトの作成

まず、既存のものを再利用するか、新規作成するかを決めてください。 アプリを構築または接続する際は、既存のプロジェクト、ブランチ、データベースを再利用するかユーザーに尋ねてください。再利用する場合は、databricks postgres list-projects（続けて list-branches／list-databases）で一覧表示し、ユーザーに選択してもらったうえで、アプリが所有するスキーマを確認します。それとも新しいプロジェクトを作成するかを尋ねてください。ユーザーから新規プロジェクトの作成を明示的に依頼された場合に限り、一覧表示を省略して直接作成してください。

databricks postgres create-project <PROJECT_ID> \
  --json '{"spec": {"display_name": "<DISPLAY_NAME>"}}' \
  --profile <PROFILE>

自動作成されるもの：production ブランチと primary 読み書き可能エンドポイント（最小／最大1 CU、スケール・トゥ・ゼロ）。処理には時間がかかります。CLI はデフォルトで完了まで待機します。すぐに戻るには --no-wait を使用してください。

作成後、次のように確認してください。

databricks postgres list-branches projects/<PROJECT_ID> --profile <PROFILE>
databricks postgres list-endpoints projects/<PROJECT_ID>/branches/<BRANCH_ID> --profile <PROFILE>
databricks postgres list-databases projects/<PROJECT_ID>/branches/<BRANCH_ID> --profile <PROFILE>

JSON 出力から接続値を抽出します。

値	JSON パス	用途
エンドポイントのホスト	status.hosts.host	PGHOST、lakebase.postgres.host
エンドポイントのリソースパス	name	LAKEBASE_ENDPOINT、lakebase.postgres.endpointPath
データベースのリソースパス	name	lakebase.postgres.database
PostgreSQL のデータベース名	status.postgres_database	PGDATABASE、lakebase.postgres.databaseName

プロジェクトの更新

databricks postgres update-project projects/<PROJECT_ID> spec.display_name \
  --json '{"spec": {"display_name": "My Updated Application"}}' \
  --profile <PROFILE>

プロジェクトの削除

警告： 削除は取り消せません。すべてのブランチ、コンピュート、データベース、ロール、データが削除されます。ユーザーの明示的な許可なしに削除しないでください。

databricks postgres delete-project projects/<PROJECT_ID> --profile <PROFILE>

オートスケーリング

エンドポイントではコンピュートユニット（CU）（CU あたり約2 GB の RAM）を使用します。範囲は、動的割り当てが0.5～32 CU、固定割り当てが36～112 CUです。スケール・トゥ・ゼロはデフォルトで有効です（タイムアウトは5分）。

サイズ設定の表、エンドポイントの CRUD、構成の詳細については、computes-and-scaling.md を参照してください。

ブランチ

ブランチはコピーオンライト方式のスナップショットです。本番環境に影響を与えずに、スキーマ移行のテスト、クエリの試行、データ変更のプレビューを行うために使用します。

databricks postgres create-branch projects/<PROJECT_ID> <BRANCH_ID> \
  --json '{"spec": {"source_branch": "projects/<PROJECT_ID>/branches/<SOURCE>", "no_expiry": true}}' \
  --profile <PROFILE>

ブランチには有効期限ポリシーが必要です。永続的にする場合は"no_expiry": true、それ以外は"ttl": "<seconds>s"（最長30日）を指定します。

制限： プロジェクトあたりアーカイブされていないブランチは10個までです。ブランチあたりの論理データは8 TBまでです。ワークスペースあたり1,000プロジェクトまでです。

ユースケース	TTL
CI/CD 環境	2--4時間（"ttl": "14400s"）
デモ	24--48時間（"ttl": "172800s"）
機能開発	1--7日（"ttl": "604800s"）
長期テスト	最長30日（"ttl": "2592000s"）

ポイントインタイムブランチ作成： 過去の状態（復元可能期間内）からブランチを作成して復旧できます。時刻指定フィールドはトップレベルのcreate-branchフラグではなく、--json仕様の中（spec.source_branch_time、spec.source_branch_lsn）にあります。

リセット： ブランチのデータとスキーマを、親ブランチの最新の内容に置き換えます。ローカルの変更は失われます。ルートブランチと子ブランチを持つブランチはリセットできません。また、保護されたブランチ（spec.is_protected）もリセットできません。

リセットはUIでのみ可能です。databricks postgres reset-branch CLIコマンドも、API/SDKメソッドもありません。 Lakebase Appで、プロジェクトのBranchesページに移動し、ブランチの横にあるメニューをクリックして、Reset from parentを選択します。

CLIでの代替手段：

• 削除して再作成： delete-branchを実行し、その後spec.source_branchに親ブランチを指定してcreate-branchを実行します（保護されている場合は、先にupdate-branchで保護を解除します）。
• ポイントインタイム： spec.source_branch_timeまたはspec.source_branch_lsnを指定してcreate-branchを実行します。タイムスタンプベースのリセットはサポートされていません。代わりにPITRブランチ作成を使用してください。

削除： 保護されたブランチは、先にupdate-branchでspec.is_protectedをfalseに設定して保護を解除する必要があります。子ブランチを持つブランチは削除できません。productionブランチは絶対に削除しないでください。

次のステップ

Databricks Appを構築する

プロジェクトを作成したら、接続されたDatabricks Appをスキャフォールドします。

# 1. Get branch name
databricks postgres list-branches projects/<PROJECT_ID> --profile <PROFILE>

# 2. Get database name
databricks postgres list-databases projects/<PROJECT_ID>/branches/<BRANCH_ID> --profile <PROFILE>

# 3. Scaffold with lakebase feature
databricks apps init --name <APP_NAME> --features lakebase \
  --set "lakebase.postgres.branch=<BRANCH_NAME>" \
  --set "lakebase.postgres.database=<DATABASE_NAME>" \
  --run none --profile <PROFILE>

アプリのワークフロー全体については、**databricks-apps**スキルを使用してください。

既存のアプリにLakebaseを接続する

上記のapps init --features lakebaseは、スキャフォールド時にデータベースを接続します。既存のアプリにプロジェクトを接続するには、そのリソースを更新します。

postgresリソースキーを使用してください。そのフィールドはbranchとdatabaseです（上の表に記載されている完全なリソースパス）。従来のdatabaseキー（instance_nameとdatabase_name）は非推奨です。これを使用するとDatabase instance <name> does not existというエラーが発生します。正確なパスはlist-branches / list-databasesで取得してください（DB名にはdatabricks-postgresのようにハイフンが含まれることがよくあります）。

アプリのリソースは**databricks apps create-updateで更新してください。これはどのアプリにも使用するメソッドです（従来のdatabricks apps updateはレガシーで、space内のアプリのリソースを変更できません）。update_mask=resourcesを指定するとresources配列全体が置き換えられるため、アプリの現在のリソースを読み取り、新しいリソースをマージ**してください（そうしないと、ほかのリソースが切り離されます）。--jsonですべてを渡し、位置引数はAPP_NAMEのみです。

databricks apps create-update <APP_NAME> --json @update.json --profile <PROFILE>   # waits for completion; --no-wait to return early

{
  "update_mask": "resources",
  "app": {
    "resources": [
      {
        "name": "postgres",
        "postgres": {
          "branch": "projects/<PROJECT_ID>/branches/<BRANCH_ID>",
          "database": "projects/<PROJECT_ID>/branches/<BRANCH_ID>/databases/<DATABASE_ID>",
          "permission": "CAN_CONNECT_AND_CREATE"
        }
      }
    ]
  }
}

ブランチとデータベースはユーザーに確認し、黙ってproductionを既定値にしないでください。 アプリのサービスプリンシパルは、そこで使用するスキーマを作成し、所有できる必要があります。そのため、対象のスキーマ名がすでにユーザー所有になっているブランチやデータベースは避けてください（SPでpermission denied … 42501が発生します）。新しい専用ブランチ、またはアプリ所有の新しいスキーマを使用するのが最適です。所有権モデルの詳細については、下記のデプロイ済みアプリのスキーマ権限を参照してください。

デプロイ済みアプリのスキーマ権限

アプリのサービスプリンシパルには CAN_CONNECT_AND_CREATE が付与されています。新しいオブジェクトは作成できますが、既存のスキーマにはアクセスできません。サービスプリンシパルがスキーマの所有者になるには、そのスキーマを作成する必要があります。

ローカルで実行する前に、必ずアプリをデプロイしてください。 これが Lakebase の権限エラーの最大の原因です。

正しいワークフロー：

1. まずデプロイします：databricks apps deploy <APP_NAME> --profile <PROFILE>
2. 必要に応じてローカルアクセス権を付与します：UI から databricks_superuser を割り当てます（プロジェクト作成者にはすでにアクセス権があります）
3. ローカルで開発します：自身の認証情報で、サービスプリンシパルが所有するスキーマへの DML アクセス権が得られます

すでに先にローカルで実行して permission denied が発生した場合：スキーマはサービスプリンシパルではなく、自身の認証情報が所有しています。ユーザーに確認せずにスキーマを削除しないでください。削除すると、すべてのデータが失われます。

ユーザーに次のいずれかを選んでもらいます：

• （A）削除して再デプロイする： databricks psql --project <PROJECT_ID> -- -c "DROP SCHEMA IF EXISTS <SCHEMA_NAME> CASCADE;" を実行し、その後アプリのディレクトリから databricks apps deploy を実行します。起動時にサービスプリンシパルがスキーマを再作成します。
• （B）先にエクスポートしてから削除し、再デプロイする： pg_dump を使用してエクスポートします（databricks postgres get-endpoint で接続情報を取得してください。HOST と TOKEN については、以下の「その他のワークフロー」を参照してください）。または、databricks psql --project <PROJECT_ID> を使用してテーブルを一時スキーマにコピーします。その後、オプション A を実行します。再デプロイ時にサービスプリンシパルがスキーマを再作成したら、pg_restore を使用するか、一時スキーマから再度 INSERT します。

その他のワークフロー

# Connect a Postgres client -- get connection string
databricks postgres get-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>

# Manage roles
databricks postgres create-role -h

# Add a read replica
databricks postgres create-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID> <ENDPOINT_ID> \
  --json '{"spec": {"type": "ENDPOINT_TYPE_READ_ONLY"}}' --profile <PROFILE>

Lakebase に対して SQL を実行する（GRANT、CREATE INDEX など）：

# 1. Get endpoint host
databricks postgres get-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>

# 2. Generate OAuth token
databricks postgres generate-database-credential \
  projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> \
  --profile <PROFILE>

# 3. Connect (use token from step 2 as password, host from step 1)
PGPASSWORD='<TOKEN>' psql "host=<HOST> user=<USERNAME> dbname=databricks_postgres sslmode=require"

注： generate-database-credential には、データベースやブランチのパスではなく、エンドポイントリソースパス（.../endpoints/<ENDPOINT_ID>）が必要です。

スクリプトで実行する方法（一括コピーして貼り付けられるので、エージェントに便利です）：

EP=projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID>
# get-endpoint JSON shape: {"status": {"hosts": {"host": "<HOSTNAME>"}, ...}, ...}
HOST=$(databricks postgres get-endpoint $EP --profile <PROFILE> -o json \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['status']['hosts']['host'])")
TOKEN=$(databricks postgres generate-database-credential $EP --profile <PROFILE> -o json \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")
PGPASSWORD="$TOKEN" psql "host=$HOST user=<USERNAME> dbname=databricks_postgres sslmode=require"

同期されたテーブルへのアプリのサービスプリンシパルのアクセス権を付与する（同期が ONLINE になり、アプリがデプロイされた後に、プロジェクト所有者として実行します）：

GRANT USAGE ON SCHEMA public TO "<SP_CLIENT_ID>";
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "<SP_CLIENT_ID>";
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "<SP_CLIENT_ID>";

最小権限にするには、public ではなく専用スキーマに同期し、同期データのみに権限を限定することを検討してください。

サービスプリンシパルのクライアント ID を取得します：databricks apps get <APP_NAME> --profile <PROFILE> → service_principal_client_id フィールド。

データ API： Postgres テーブルに対する PostgREST 互換の HTTP CRUD です。connectivity.md を参照してください。 同期テーブル： Delta テーブルを Lakebase に同期します。synced-tables.md を参照してください。

PostgreSQL 拡張機能

Lakebase は PostgreSQL 拡張機能をサポートしています（ベクトル埋め込み用の pgvector、クエリ統計用の pg_stat_statements など）。サポートされている拡張機能の一覧を参照してください。

-- List available extensions
SELECT * FROM pg_available_extensions ORDER BY name;

-- Install an extension
CREATE EXTENSION IF NOT EXISTS <extension_name>;

pgvector を使ったベクトル埋め込みについては、pgvector.md を参照してください。

トラブルシューティング

エラー	解決方法
cannot configure default credentials	--profile フラグを使うか、先に認証してください
PERMISSION_DENIED	ワークスペースの権限を確認してください
permission denied for schema	スキーマは別のロールが所有しています。アプリをまだデプロイしていない場合：先にデプロイして、SP がスキーマを作成して所有するようにしてください。デプロイ済みなのにこのエラーが発生する場合（開発者が先にローカルで実行した場合）：データ損失の可能性をユーザーに警告し、先にエクスポートする方法（databricks postgres get-endpoint で取得した接続情報を使った pg_dump、または databricks psql による一時スキーマへのコピー）を提示してから、DROP SCHEMA IF EXISTS <SCHEMA_NAME> CASCADE を実行して再デプロイしてください。
保護されたブランチを削除できない	先に update-branch を使い、spec.is_protected を false に設定してください
長時間実行される操作がタイムアウトする	--no-wait を使い、get-operation でポーリングしてください
長時間のクエリ中にトークンの有効期限が切れる	トークンの有効期限は 1 時間です。更新処理を実装してください（connectivity.md を参照）
スケール・トゥ・ゼロ後に接続が拒否される	コンピュートは約 100ms で起動します。再試行ロジックを実装してください
ブランチの削除がブロックされる	先に子ブランチを削除してください
オートスケーリングの範囲が広すぎる	最大値 - 最小値は 16 CU を超えられません
SSL が必要というエラー	常に sslmode=require を使ってください
更新マスクが必要	すべての update-* 操作でフィールドの指定が必要です（-h を参照）
アイドル状態の後に接続が切断される	アイドルタイムアウトは 24 時間です。24 時間を超える最大接続時間は保証されません。再試行を実装してください。
DNS の名前解決に失敗する（macOS）	長いホスト名では Python の socket.getaddrinfo() が失敗します。dig で IP アドレスを解決し、TLS SNI 用の host と併せて hostaddr パラメーターに渡してください。connectivity.md を参照してください。
storage_catalog パイプラインの失敗	new_pipeline_spec.storage_catalog は通常の UC カタログである必要があり、Lakebase カタログは指定できません。DLT は Postgres をバックエンドとするスキーマにイベントログを書き込めません。
同期テーブルの CDF エラー	ソースで CDF を有効にしてください：ALTER TABLE ... SET TBLPROPERTIES (delta.enableChangeDataFeed = true)。Triggered モードおよび Continuous モードで必要です。
同期の権限エラー	ソーステーブルに対する USE CATALOG／USE SCHEMA と、ストレージカタログ内での CREATE TABLE を確認してください
同期テーブルにヌルバイトが含まれる	STRING／ARRAY／MAP／STRUCT 列にヌルバイト（0x00）が含まれていると、同期に失敗します。ソースデータをサニタイズしてください：REPLACE(col, CAST(CHAR(0) AS STRING), '')
同期テーブルのデータが変更される	Postgres の同期テーブルで許可されるのは読み取りクエリ、インデックス、DROP TABLE のみです。変更すると同期パイプラインが壊れます。
DAB の synced_database_tables	非推奨です。レガシー API に対応しているため、現在の Lakebase では失敗します。代わりに postgres_synced_tables バンドルリソース（Beta、CLI v1.0.0 以降）または databricks postgres create-synced-table CLI を使ってください。

SDK とバージョンの要件

コンポーネント	最小バージョン
Databricks CLI	>= v0.294.0
Databricks SDK for Python	>= 0.81.0（w.postgres モジュールに必要）
psycopg	2.x または 3.x（非同期処理／プーリングには 3.x を推奨）
Postgres	16 または 17（デフォルト：PG 17）