databricks-lakebase

Lakebase Postgres 自动扩缩

首先：使用父级 databricks-core 技能了解 CLI 基础知识、身份验证和配置文件选择。

Lakebase 是 Databricks 提供的无服务器、兼容 Postgres 的数据库，在 AWS 和 Azure 上均已正式发布（GA）。它提供完全托管的 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 流程（请参阅“常见问题”行和 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）
分支	不支持	完全支持
缩减至零	不支持	可配置
高可用性	可读次级节点	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 — 规格配置、端点管理、缩减至零、高可用性
• connectivity.md — 连接模式、令牌刷新、Data API
• synced-tables.md — Lakebase 同步表、数据类型映射、容量规划
• lakehouse-sync.md — 将 Lakebase Postgres 中的 CDC 同步到 Unity Catalog Delta 表（可通过 databricks postgres *-cdf-config / w.postgres.*_cdf_config 编程配置，Beta）
• pgvector.md — 使用 pgvector 扩展进行向量相似度搜索
• off-platform.md — 平台外 Lakebase（非 Databricks Apps）：外部 Node.js 应用通过 @databricks/lakebase 连接、环境管理、令牌刷新、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 内存）。范围：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"）

**时间点分支：**从过去的状态（在恢复窗口内）创建分支以进行恢复。时间指定字段位于 --json 规范内部（spec.source_branch_time、spec.source_branch_lsn），而非顶层的 create-branch 标志。

**重置：**将分支数据和架构替换为其父分支的最新内容。本地变更会丢失。根分支和包含子分支的分支无法重置；受保护的分支（spec.is_protected）也无法重置。

**重置仅能通过 UI 操作——没有 databricks postgres reset-branch CLI 命令，也没有 API/SDK 方法。**在 Lakebase App 中，前往项目的 Branches 页面，点击分支旁边的菜单，然后选择 Reset from parent。

CLI 替代方案：

• **删除并重新创建：**运行 delete-branch，然后运行 create-branch，并将 spec.source_branch 设为父分支（如果分支受保护，请先通过 update-branch 取消保护）。
• **时间点：**运行 create-branch 并指定 spec.source_branch_time 或 spec.source_branch_lsn。不支持基于时间戳的重置；请改用 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）——使用全新/专用分支或新建由应用拥有的架构最为合适。完整的所有权模型请参阅下文的 Schema Permissions for Deployed Apps。

已部署应用的架构权限

应用的 Service Principal 拥有 CAN_CONNECT_AND_CREATE 权限——可以创建新对象，但无法访问现有架构。SP 必须先创建架构，才能成为其所有者。

务必先部署应用，再在本地运行。 这是 Lakebase 权限错误的首要来源。

正确的工作流：

1. 先部署：databricks apps deploy <APP_NAME> --profile <PROFILE>
2. 授予本地访问权限（如有需要）：通过 UI 分配 databricks_superuser（项目创建者已拥有访问权限）
3. 在本地开发：你的凭据可对 SP 所有的架构执行 DML 操作

如果你已经先在本地运行并遇到 permission denied：该架构由你的凭据所有，而非 SP 所有。未经用户同意，请勿删除该架构——删除会清空所有数据。

请让用户选择：

• (A) 删除并重新部署： databricks psql --project <PROJECT_ID> -- -c "DROP SCHEMA IF EXISTS <SCHEMA_NAME> CASCADE;"，然后从应用目录运行 databricks apps deploy。SP 会在启动时重新创建该架构。
• (B) 先导出，再删除并重新部署： 使用 pg_dump 导出（从 databricks postgres get-endpoint 获取连接信息；HOST 和 TOKEN 见下方的 其他工作流），或使用 databricks psql --project <PROJECT_ID> 将表复制到临时架构，然后执行选项 A。SP 在重新部署时重新创建架构后，使用 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 需要 endpoint 资源路径（.../endpoints/<ENDPOINT_ID>），而非数据库或分支路径。

可编写脚本的版本（一次复制粘贴，适用于 Agent）：

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"

授予应用 SP 对同步表的访问权限（同步状态为 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，这样授予的权限仅适用于同步数据。

获取 SP 客户端 ID：databricks apps get <APP_NAME> --profile <PROFILE> → service_principal_client_id 字段。

Data API： 兼容 PostgREST 的 Postgres 表 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）
空闲后连接关闭	空闲超时为 24h；无法保证连接的最长生命周期超过 24h。请实现重试。
DNS 解析失败（macOS）	使用较长主机名时，Python socket.getaddrinfo() 会失败。请使用 dig 解析 IP，并在 host 旁通过 hostaddr 参数传入（用于 TLS SNI）。参见 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。修改会导致同步管道中断。
DABs synced_database_tables	已弃用 — 它映射到旧版 API，在当前 Lakebase 上会失败。请改用 postgres_synced_tables bundle 资源（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）