databricks-lakebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lakebase Postgres Autoscaling

Lakebase Postgres 自动扩缩容

FIRST: Use the parent

databricks

skill for CLI basics, authentication, and profile selection.

Lakebase is Databricks' serverless Postgres-compatible database (similar to Neon). It provides fully managed OLTP storage with autoscaling, branching, and scale-to-zero.

Manage Lakebase Postgres projects, branches, endpoints, and databases via

databricks postgres

CLI commands.

第一步：如需了解CLI基础操作、身份验证和配置文件选择，请使用父级

databricks

技能。

Lakebase是Databricks推出的无服务器Postgres兼容数据库（与Neon类似）。它提供全托管的OLTP存储，支持自动扩缩容、分支功能和缩容至零。

可通过

databricks postgres

CLI命令管理Lakebase Postgres的项目、分支、端点和数据库。

Resource Hierarchy

资源层级

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

Project: Top-level container. Creating one auto-provisions a
```
production
```
branch and a
```
primary
```
read-write endpoint.
Branch: Isolated database environment sharing storage with parent (copy-on-write). States:
```
READY
```
,
```
ARCHIVED
```
.
Endpoint (called Compute in the Lakebase UI): Compute resource powering a branch. Types:
```
ENDPOINT_TYPE_READ_WRITE
```
,
```
ENDPOINT_TYPE_READ_ONLY
```
(read replica).
Database: Standard Postgres database within a branch. Default:
```
databricks_postgres
```
.
Role: Postgres role within a branch. Manage roles via
```
databricks postgres create-role -h
```
.

Project (顶级容器)
  └── Branch (隔离的数据库环境，写时复制)
        ├── Endpoint (读写或只读)
        ├── Database (标准Postgres数据库)
        └── Role (Postgres角色)

Project：顶级容器。创建项目时会自动预配置一个
```
production
```
分支和一个
```
primary
```
读写端点。
Branch：与父级共享存储的隔离数据库环境（写时复制）。状态包括：
```
READY
```
、
```
ARCHIVED
```
。
Endpoint（Lakebase UI中称为Compute）：为分支提供算力的资源。类型包括：
```
ENDPOINT_TYPE_READ_WRITE
```
、
```
ENDPOINT_TYPE_READ_ONLY
```
（只读副本）。
Database：分支内的标准Postgres数据库。默认数据库为
```
databricks_postgres
```
。
Role：分支内的Postgres角色。可通过
```
databricks postgres create-role -h
```
管理角色。

Resource Name Formats

资源命名格式

Resource	Format
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}`

All IDs: 1-63 characters, start with lowercase letter, lowercase letters/numbers/hyphens only (RFC 1123).

资源	格式
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规范）。

CLI Discovery — ALWAYS Do This First

CLI 命令探索 — 请务必先执行此步骤

Note: "Lakebase" is the product name; the CLI command group is
postgres
. All commands use
databricks postgres ...
.

Do NOT guess command syntax. Discover available commands and their usage dynamically:

bash

undefined

注意：产品名称为"Lakebase"；CLI命令组为
postgres
。所有命令均使用
databricks postgres ...
格式。

请勿猜测命令语法。请动态探索可用命令及其用法：

bash

undefined

List all postgres subcommands

列出所有postgres子命令

databricks postgres -h

Get detailed usage for any subcommand (flags, args, JSON fields)

获取任意子命令的详细用法（参数、选项、JSON字段）

databricks postgres <subcommand> -h


Run `databricks postgres -h` before constructing any command. Run `databricks postgres <subcommand> -h` to discover exact flags, positional arguments, and JSON spec fields for that subcommand.

databricks postgres <subcommand> -h


在构造任何命令之前，请先运行`databricks postgres -h`。运行`databricks postgres <subcommand> -h`可查看该子命令的确切参数、位置变量和JSON规范字段。

Create a Project

创建项目

Do NOT list projects before creating.

bash

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

Auto-creates:
```
production
```
branch +
```
primary
```
read-write endpoint (1 CU min/max, scale-to-zero)
Long-running operation; the CLI waits for completion by default. Use
```
--no-wait
```
to return immediately.

Run

databricks postgres create-project -h

for all available spec fields (e.g.

pg_version

After creation, verify the auto-provisioned resources:

bash

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>

请勿在创建项目前列出项目。

bash

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

自动创建：
```
production
```
分支 +
```
primary
```
读写端点（最小/最大1 CU，支持缩容至零）
属于长时间运行的操作；默认情况下CLI会等待操作完成。使用
```
--no-wait
```
参数可立即返回。
运行
```
databricks postgres create-project -h
```
查看所有可用的规范字段（例如
```
pg_version
```
）。

创建完成后，验证自动预配置的资源：

bash

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>

Autoscaling

自动扩缩容

Endpoints use compute units (CU) for autoscaling. Configure min/max CU via

create-endpoint

update-endpoint

. Run

databricks postgres create-endpoint -h

to see all spec fields.

Scale-to-zero is enabled by default. When idle, compute scales down to zero; it resumes in seconds on next connection.

端点使用**计算单元（CU）**实现自动扩缩容。可通过

create-endpoint

或

update-endpoint

配置最小/最大CU值。运行

databricks postgres create-endpoint -h

查看所有规范字段。

默认启用缩容至零功能。当端点处于空闲状态时，计算资源会缩容至零；下次有连接请求时，会在数秒内恢复。

Branches

分支

Branches are copy-on-write snapshots of an existing branch. Use them for experimentation: testing schema migrations, trying queries, or previewing data changes -- without affecting production.

bash

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

Branches require an expiration policy: use

"no_expiry": true

for permanent branches.

When done experimenting, delete the branch. Protected branches must be unprotected first -- use

update-branch

to set

spec.is_protected

false

, then delete:

bash

undefined

分支是现有分支的写时复制快照。可用于实验场景：测试架构迁移、尝试查询或预览数据变更——且不会影响生产环境。

bash

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

分支需要设置过期策略：如需创建永久分支，请使用

"no_expiry": true

。

实验完成后，可删除分支。受保护的分支需先取消保护——使用

update-branch

将

spec.is_protected

设置为

false

，然后再删除：

bash

undefined

Step 1 — unprotect

第一步 — 取消保护

databricks postgres update-branch projects/<PROJECT_ID>/branches/<BRANCH_ID>
--json '{"spec": {"is_protected": false}}' --profile <PROFILE>

Step 2 — delete (run -h to confirm positional arg format for your CLI version)

第二步 — 删除（运行-h确认你的CLI版本对应的位置参数格式）

databricks postgres delete-branch projects/<PROJECT_ID>/branches/<BRANCH_ID>
--profile <PROFILE>


**Never delete the `production` branch** — it is the authoritative branch auto-provisioned at project creation.

databricks postgres delete-branch projects/<PROJECT_ID>/branches/<BRANCH_ID>
--profile <PROFILE>


**请勿删除`production`分支**——它是项目创建时自动预配置的权威分支。

What's Next

后续操作

Build a Databricks App

构建Databricks应用

After creating a Lakebase project, scaffold a Databricks App connected to it.

Step 1 — Discover branch name (use

.name

from a

READY

branch):

bash

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

Step 2 — Discover database name (use

.name

from the desired database;

<BRANCH_ID>

is the branch ID, not the full resource name):

bash

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

Step 3 — Scaffold the app with the

lakebase

feature:

bash

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

Where

<BRANCH_NAME>

is the full resource name (e.g.

projects/<PROJECT_ID>/branches/<BRANCH_ID>

) and

<DATABASE_NAME>

is the full resource name (e.g.

projects/<PROJECT_ID>/branches/<BRANCH_ID>/databases/<DB_ID>

For the full app development workflow, use the databricks-apps
skill.

创建Lakebase项目后，可搭建一个连接到该项目的Databricks应用。

第一步 — 查看分支名称（从

READY

状态的分支中获取

.name

字段）：

bash

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

第二步 — 查看数据库名称（从目标数据库中获取

.name

字段；

<BRANCH_ID>

为分支ID，而非完整资源名称）：

bash

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

第三步 — 使用
lakebase
功能搭建应用：

bash

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

其中

<BRANCH_NAME>

为完整资源名称（例如

projects/<PROJECT_ID>/branches/<BRANCH_ID>

），

<DATABASE_NAME>

为完整资源名称（例如

projects/<PROJECT_ID>/branches/<BRANCH_ID>/databases/<DB_ID>

）。

如需了解完整的应用开发流程，请使用**

databricks-apps

**技能。

Other Workflows

其他工作流

Connect a Postgres client Get the connection string from the endpoint, then connect with psql, DBeaver, or any standard Postgres client.

bash

databricks postgres get-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>

Manage roles and permissions Create Postgres roles and grant access to databases or schemas.

bash

databricks postgres create-role -h   # discover role spec fields

Add a read-only endpoint Create a read replica for analytics or reporting workloads to avoid contention on the primary read-write endpoint.

bash

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

连接Postgres客户端 从端点获取连接字符串，然后使用psql、DBeaver或任何标准Postgres客户端进行连接。

bash

databricks postgres get-endpoint projects/<PROJECT_ID>/branches/<BRANCH_ID>/endpoints/<ENDPOINT_ID> --profile <PROFILE>

管理角色和权限 创建Postgres角色，并授予数据库或模式的访问权限。

bash

databricks postgres create-role -h   # 探索角色规范字段

添加只读端点 为分析或报表工作负载创建只读副本，避免对主读写端点造成资源竞争。

bash

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

Troubleshooting

故障排除

Error	Solution
`cannot configure default credentials`	Use `--profile` flag or authenticate first
`PERMISSION_DENIED`	Check workspace permissions
Protected branch cannot be deleted	`update-branch` to set `spec.is_protected` to `false` first
Long-running operation timeout	Use `--no-wait` and poll with `get-operation`

错误	解决方案
`cannot configure default credentials`	使用 `--profile` 参数或先完成身份验证
`PERMISSION_DENIED`	检查工作区权限
受保护分支无法删除	先使用 `update-branch` 将 `spec.is_protected` 设置为 `false`
长时间运行的操作超时	使用 `--no-wait` 参数，然后通过 `get-operation` 轮询操作状态