开始使用适用于 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

使用实际的工作区 URL 替换 https://your-workspace.cloud.databricks.com。 此命令将打开浏览器窗口，以便使用 OAuth 通过 Azure Databricks 帐户进行身份验证。

有关更多身份验证选项，请参阅 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

该命令返回可与 PostgreSQL 客户端一起使用的 OAuth 令牌，例如 psql 使用 Databricks 标识访问数据。 有关使用 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 替换为实际值：

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/production",
      "no_expiry": true
    }
  }'

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_protectedtrue，使分支受到保护。 更新掩码 （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 （60s–604800s） 以定义非活动超时，或 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标识的 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）。

更新角色

使用更新掩码模式更新角色。 将更新掩码作为第二个位置参数传递。

更新 spec.attributes时，必须提供所有三个属性字段 ， 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 数据库中，以便进行低延迟的操作读取。 将 create-synced-table 与 {catalog}.{schema}.{table} ID 一起使用：

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 其中包含这些字段的新值。 仅修改更新掩码中列出的字段。

其他资源

• Databricks CLI PostgreSQL 命令参考
• 创建 Postgres 角色
• 使用 psql 进行连接
• 管理分支
• 配置自动缩放
• 使用同步表为湖仓一体提供数据