开始使用适用于 Lakebase 的 Databricks CLI

重要

Lakebase 自动缩放在以下区域处于 Beta 版本：eastus2，westeurope，westus。

Lakebase 自动缩放是最新版本的 Lakebase，可自动缩放计算、缩放到零、分支和即时还原。有关与 Lakebase 预配的功能比较，请参阅在版本之间进行选择。

本指南可帮助你开始使用 Databricks CLI 来管理 Lakebase 项目、分支和计算（终结点）。你将了解如何在几个命令中创建工作项目。

有关完整的命令参考和所有可用选项，请参阅 Databricks CLI postgres 命令。

先决条件

Databricks CLI：安装 Databricks CLI。请参阅安装 Databricks CLI。
工作区访问权限：必须有权访问 Lakebase 资源所在的 Azure Databricks 工作区。

使用 Databricks 进行身份验证

在运行任何 CLI 命令之前，请使用 Azure Databricks 工作区进行身份验证：

databricks auth login --host https://your-workspace.cloud.databricks.com

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

注释

如果您有多个配置文件，请使用--profile标志来指定哪个要使用的配置文件：databricks postgres <command> --profile my-profile 若要查看配置文件，请运行 databricks auth profiles。

有关更多身份验证选项，请参阅 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（例如 br-divine-sea-y2k942xa，）。

（可选）将分支 ID 导出为变量，以便在后续命令中使用：

export BRANCH_ID="br-divine-sea-y2k942xa"

用列表输出中的实际默认分支 ID 替换 br-divine-sea-y2k942xa。

3.获取终结点 ID

列出分支中的终结点。默认分支会自动包含一个读写端点：

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

记下字段中的 name 终结点 ID。它将采用格式 projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}。提取终结点 ID（例如 ep-plain-sunset-y2vc0zan），并选择将其导出为变量：

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

将 ep-plain-sunset-y2vc0zan 替换为列表输出中的实际终结点 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

这会返回详细的分支信息，包括当前状态、默认分支状态、保护状态、逻辑大小、源分支详细信息（如果从另一个分支），以及创建/更新时间戳。

获取有关终结点的详细信息：

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

这会返回详细的终结点配置，包括终结点类型（读写或只读）、自动缩放设置（最小和最大计算单位）、当前状态（ACTIVE、IDLE 等）、连接主机、暂停超时和创建/更新时间戳。

更新资源

使用更新掩码模式更新资源。更新掩码指定要更新的字段：

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 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
    }
  }'

常见工作流

从生产环境创建功能分支

基于现有分支创建新分支以测试更改。指定source_branch时，创建的新分支将具有与源分支相同的架构和数据。将项目和分支 ID 替换为实际值：

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

注释

创建分支时，必须指定过期策略。用于 no_expiry: true 创建永久分支。

若要在特定的 JSON 规范（如 $PROJECT_ID 或 $BRANCH_ID）中使用 shell 变量，需要对 --json 的值使用双引号并对内部引号进行转义。

功能分支需要一个读写计算端点以允许数据库操作。

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

在功能分支上完成开发和测试后，可以将其删除：

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

注释

删除命令会立即返回，但实际删除可能需要一段时间才能完成。可以通过运行相应的 get 资源命令来验证删除，该命令在完全删除资源后返回错误。

使用只读副本缩放读取

添加只读副本以处理增加的读取流量。此示例将只读副本添加到默认生产分支：

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 等) 来分配读取工作负载。

了解关键概念

长时间运行的操作

创建、更新和删除命令是长时间运行的操作。默认情况下，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 其中包含这些字段的新值。仅修改更新掩码中列出的字段。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-02-07