SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场databricks-lakebase

databricks-lakebase

数据与分析

查看项目

更新于 10-14 10:18

技能介绍

用途

Lakebase 是 Databricks 的无服务器、PostgreSQL 兼容数据库，可在 AWS 和 Azure 上使用（GA）。它提供全托管的 OLTP 存储，具备自动扩缩容、分支和缩容至零能力。本技能覆盖 Lakebase 数据库、OLTP 存储、项目生命周期、扩缩容、连接、同步表以及 Data API 等相关操作。

使用前提：请先使用父级 databricks-core 技能了解 CLI 基础、认证和配置文件选择。

重要：Lakebase 目前仅提供自动扩缩容（Autoscaling）版本，已不存在 Provisioned 版本——不要创建 Provisioned 实例。旧的 Provisioned 层（静态、不可扩展的 Postgres；通过 databricks database CLI / w.database SDK 操作）将在 2026 年夏季迁移至 Autoscaling，客户无需采取任何操作。若用户请求 Provisioned 实例，应告知其 Provisioned 实例已不存在，并引导使用 Autoscaling。应用配置中的旧版 database 资源键视为已弃用，应迁移至 postgres 资源键。对于旧版 DAB 的 synced_database_tables 资源，应改用 databricks postgres create-synced-table CLI 流程。

主要能力

  • 项目生命周期：创建、更新、删除 Lakebase Postgres Autoscaling 项目
  • 分支：写时复制（copy-on-write）分支，带 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 应用集成：通过 Lakebase 功能脚手架应用，采用 deploy-first 工作流
  • 云支持：AWS 和 Azure（GA）

合规：支持 HIPAA、C5、TISAX 或 None。

资源层级

  • Project（顶层容器）：创建时会自动置备一个 production 分支和一个主读写端点。
  • Branch（分支）：与父级共享存储的隔离数据库环境（写时复制）。状态：READY、ARCHIVED。
  • Endpoint（端点）：为分支提供动力的计算资源（UI 中称为 Compute）。类型：ENDPOINT_TYPE_READ_WRITE、ENDPOINT_TYPE_READ_ONLY。
  • Database（数据库）：分支内的标准 Postgres 数据库。默认：databricks_postgres。
  • Role（角色）：分支内的 Postgres 角色。

资源名称格式：Project 为 projects/{project_id}；Branch 为 projects/{project_id}/branches/{branch_id}；Endpoint 为 projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}；Database 为 projects/{project_id}/branches/{branch_id}/databases/{database_id}。所有 ID 为 1-63 个字符，以小写字母开头，仅含小写字母、数字和连字符（RFC 1123）。

使用方式

注意：Lakebase 是产品名，CLI 命令组是 postgres。所有命令均使用 databricks postgres ...。不要猜测命令语法，应动态发现可用命令：

databricks postgres -h

databricks postgres <subcommand> -h

创建项目：先决定复用还是创建。构建或附加到应用时，询问用户是复用现有项目/分支/数据库（用 databricks postgres list-projects 列出，再 list-branches / list-databases），还是创建新项目。仅当用户明确要求全新项目时才直接创建。

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

更新项目：

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>

创建分支：

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

分支限制：每项目 10 个未归档分支；每分支 8 TB 逻辑数据；每工作区 1,000 个项目。

运行 SQL：

  1. 获取端点主机：databricks postgres get-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>
  2. 生成 OAuth 令牌：databricks postgres generate-database-credential projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>
  3. 连接：PGPASSWORD='<TOKEN>' psql "host=<HOST> user=<USERNAME> dbname=databricks_postgres sslmode=require"

构建 Databricks 应用：

databricks apps init --name <APP_NAME> --features lakebase --set "lakebase.postgres.branch=<BRANCH_NAME>" --set "lakebase.postgres.database=<DATABASE_NAME>" --run none --profile <PROFILE>

附加 Lakebase 到现有应用时，使用 postgres 资源键（字段为 branch + database 的完整资源路径）。旧版 database 键（instance_name + database_name）已弃用。

适用场景

  • 需要全托管 OLTP 存储的应用
  • 数据库模式迁移测试、查询试验、数据变更预览（使用分支）
  • 将 Unity Catalog Delta 表同步到 Postgres
  • 为 Databricks 应用提供 Postgres 后端
  • 使用 pgvector 进行向量相似度搜索

限制

  • Lakebase 目前仅支持 Autoscaling，Provisioned 层已不存在
  • 分支上限：每项目 10 个未归档分支；每分支 8 TB 逻辑数据；每工作区 1,000 个项目
  • 分支过期策略：no_expiry 或 TTL（最长 30 天）
  • 令牌 1 小时后过期，需实现刷新
  • 重置（Reset）仅限 UI 操作，无 CLI 命令或 API/SDK 方法；受保护分支和含子分支的分支不可重置
  • 受保护分支须先取消保护才能删除；不能删除含子分支的分支；绝不能删除 production 分支
  • 应用的服务主体（SP）需自行创建 schema 才能成为所有者；始终先部署应用再本地运行

故障排查

  • cannot configure default credentials：使用 --profile 标志或先认证
  • PERMISSION_DENIED：检查工作区权限
  • permission denied for schema：schema 归另一角色所有。若应用未部署，先部署让 SP 创建并拥有 schema；若已部署但仍报此错（本地先运行过），提醒用户数据丢失风险，可先导出（用 databricks postgres get-endpoint 的连接信息执行 pg_dump，或通过 databricks psql 复制到临时 schema），然后 DROP SCHEMA IF EXISTS <SCHEMA_NAME> CASCADE 并重新部署
  • 受保护分支无法删除：先 update-branch 将 spec.is_protected 设为 false
  • 长时间运行操作超时：使用 --no-wait 并用 get-operation 轮询
  • 长时间查询期间令牌过期：令牌 1 小时后过期，需实现刷新