Lakebase API 指南

本页概述了 Lakebase API，包括认证、可用端点以及使用 REST API、Databricks CLI 和 Databricks SDK（Python、Java、Go）的常见模式。

有关操作及其参数的完整列表，请参见 Postgres API 参考文献。

注释

部分运营仍在 Beta阶段。 Postgres API 参考文档标明了每项操作的状态。

Authentication

Lakebase API 使用 工作区级 OAuth 认证 来管理项目基础设施（创建项目、配置设置等）。

注释

两种类型的连接：此 API 用于 平台管理 （创建项目、分支、计算）。对于 数据库访问 （连接到查询数据）：

SQL 客户端 （psql、pgAdmin、DBeaver）：使用 Lakebase OAuth 令牌或 Postgres 密码。请参阅身份验证。
数据 API （RESTful HTTP）：使用 Lakebase OAuth 令牌。请参阅数据 API。
编程语言驱动程序 （psycopg、SQLAlchemy、JDBC）：使用 Lakebase OAuth 令牌或 Postgres 密码。请参阅快速入门。

有关这两个身份验证层的完整说明，请参阅身份验证体系结构。

设置身份验证

使用 Databricks CLI 进行身份验证：

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

按照浏览器提示登录。 CLI 将 OAuth 令牌缓存在 ~/.databricks/token-cache.json.

然后选择访问方法：

Python SDK

SDK 使用统一身份验证并自动处理 OAuth 令牌：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

Java SDK

SDK 使用统一身份验证并自动处理 OAuth 令牌：

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

CLI

命令自动使用缓存的令牌：

databricks postgres list-projects

curl

为直接 API 调用生成令牌：

export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

curl -X GET "https://your-workspace.cloud.databricks.com/api/2.0/postgres/projects" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

OAuth 令牌在一小时后过期。根据需要重新生成。

有关详细信息，请参阅授权用户使用 OAuth 访问 Databricks。

可用端点

所有终结点都使用基路径 /api/2.0/postgres/。

项目

操作	方法	端点	Documentation
创建项目	`POST`	`/projects`	创建项目
更新项目	`PATCH`	`/projects/{project_id}`	常规设置
删除项目	`DELETE`	`/projects/{project_id}`	删除项目
获取项目	`GET`	`/projects/{project_id}`	获取项目详细信息
列出项目	`GET`	`/projects`	列出项目

分支

操作	方法	端点	Documentation
创建分支	`POST`	`/projects/{project_id}/branches`	创建分支
更新分支	`PATCH`	`/projects/{project_id}/branches/{branch_id}`	更新分支设置
删除分支	`DELETE`	`/projects/{project_id}/branches/{branch_id}`	删除分支
获取分支	`GET`	`/projects/{project_id}/branches/{branch_id}`	查看分支
列出分支	`GET`	`/projects/{project_id}/branches`	列出分支

端点（计算实例和读取副本）

在 API 中，计算称为 终结点。有关概念性概述，请参阅计算和终结点。

下表将 UI 概念映射到其 API 等效项：

UI 概念	API 资源或字段	Documentation
主要计算	带有 `endpoint_type: ENDPOINT_TYPE_READ_WRITE` 的端点	管理计算
只读副本	带有 `endpoint_type: ENDPOINT_TYPE_READ_ONLY` 的端点	管理只读副本
高可用性	`group` 端点规格中的字段（`EndpointGroupSpec`）	管理高可用性
计算标识符（UID、资源名称）	端点对象上的 `uid` 和 `name`（完整资源路径）	计算标识符

可用操作

操作	方法	端点	Documentation
创建终结点	`POST`	`/projects/{project_id}/branches/{branch_id}/endpoints`	创建只读副本
更新端点	`PATCH`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	编辑计算实例 / 编辑只读副本 / 管理高可用性
删除终结点	`DELETE`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	删除只读副本
获取端点	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}`	查看计算资源
列出终结点	`GET`	`/projects/{project_id}/branches/{branch_id}/endpoints`	查看计算资源

角色

操作	方法	端点	Documentation
列出角色	`GET`	`/projects/{project_id}/branches/{branch_id}/roles`	查看 Postgres 角色
创建角色	`POST`	`/projects/{project_id}/branches/{branch_id}/roles`	创建 OAuth 角色 \| 创建密码角色
获取角色	`GET`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	查看 Postgres 角色
更新角色	`PATCH`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	更新角色
删除角色	`DELETE`	`/projects/{project_id}/branches/{branch_id}/roles/{role_id}`	删除角色

操作	方法	端点	Documentation
将数据库注册到 Unity 目录	`POST`	`/catalogs`	注册数据库
获取目录注册	`GET`	`/catalogs/{catalog_id}`	检查注册状态
删除目录注册项	`DELETE`	`/catalogs/{catalog_id}`	取消注册数据库

同步表

操作	方法	端点	Documentation
创建同步表	`POST`	`/synced_tables`	创建同步表
获取同步表	`GET`	`/synced_tables/{table_name}`	检查同步状态
删除同步表	`DELETE`	`/synced_tables/{table_name}`	删除同步表

注释

在路径table_name中使用catalog.schema.table格式。

创建和删除是长时间运行的操作。轮询返回的操作，直到 done: true。请参阅长时间运行的操作。

删除同步表只会移除 Unity Catalog 的注册。单独删除 Postgres 表以释放空间。

变更数据流

Lakebase Change Data Feed (CDF) 操作范围限定为分支。关于请求和响应的详细信息，请参见 Postgres API参考中的CDF操作。

操作	方法	Documentation
创建 CDF 配置	`POST`	启动变更数据流
获得CDF身份	`GET`	启动变更数据流
CDF状态列表	`GET`	启动变更数据流
获取CDF配置	`GET`	启动变更数据流
删除 CDF 配置	`DELETE`	禁用 Lakebase CDF

注释

创建一个 CDF 配置以启动变更数据流。你也可以从Lakebase的界面开始订阅。参见 “开始变更数据流”。

删除 CDF 配置会永久移除该配置及其表映射关系，但 Unity Catalog 中的目标 Delta 表会被保留。

数据库凭据

操作	方法	端点	Documentation
生成数据库凭据	`POST`	`/credentials`	OAuth 令牌身份验证

操作

操作	方法	端点	Documentation
获取操作	`GET`	`/projects/{project_id}/operations/{operation_id}`	请参阅以下示例

权限

项目 ACL 权限使用标准的 Azure Databricks 权限 API，而非 /api/2.0/postgres/ 基路径。将 request_object_type 设置为 database-projects，并将 request_object_id 设置为你的项目 ID（例如 my-app）。

操作	方法	端点	Documentation
获取项目权限	`GET`	`/api/2.0/permissions/database-projects/{project_id}`	权限 API 参考
更新项目权限	`PATCH`	`/api/2.0/permissions/database-projects/{project_id}`	权限 API 参考
更换项目权限	`PUT`	`/api/2.0/permissions/database-projects/{project_id}`	权限 API 参考

Lakebase 项目的可授予权限级别是 CAN_USE 和 CAN_MANAGE。 CAN_CREATE 是继承的级别，不能通过 API 设置。请参阅权限级别。

有关用法示例和 CLI/SDK/Terraform 等效项，请参阅以编程方式授予权限。

获取操作

通过资源名称检查长期运行操作的状态。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation (example: create project)
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)
print(f"Operation started: {operation.name()}")

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation (example: create project)
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);
System.out.println("Operation started: " + operation.getName());

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

CLI

默认情况下，CLI 会自动等待操作完成。使用 --no-wait 跳过轮询。

# Create project without waiting
databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

# Later, check the operation status using the operation name from the response
databricks postgres get-operation projects/my-project/operations/<operation-id>

curl

# Get operation status
curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

响应格式：

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/databricks.postgres.v1.Project",
    "name": "projects/my-project",
    ...
  }
}

领域：

done：false 进行中，true 完成时
response：包含当 done 是 true 时的结果
error：包含错误详细信息（如果操作失败）

常见模式

资源命名

资源遵循分层命名模式，子资源的范围受其父资源限制。

项目使用此格式：

projects/{project_id}

诸如操作之类的子资源嵌套在其父项目之下：

projects/{project_id}/operations/{operation_id}

这意味着您需要父项目 ID 才能访问操作或其他子资源。

资源 ID：

创建资源时，必须为my-app、project_id或branch_id参数提供资源 ID（例如endpoint_id）。此 ID 将成为 API 调用中资源路径的一部分（例如 projects/my-app/branches/development）。

可以选择提供一个 display_name 用于为资源提供更具描述性的标签。如果未指定显示名称，系统将资源 ID 用作显示名称。

：：：tip 在 UI 中查找资源

要在 Lakebase 应用中查找项目，请在项目列表中查找其显示名称。如果在创建项目时未提供自定义显示名称，请搜索你的 project_id （如“my-app”）。

:::

注释

创建后无法更改资源 ID。

要求：

长度必须为 1-63 个字符
仅小写字母、数字和连字符
不能以连字符开头或结尾
示例：my-app、、 analytics-dbcustomer-123

长期运行的操作 (LRO)

创建、更新和删除操作返回一个提供完成状态的 databricks.longrunning.Operation 对象。

操作响应示例：

{
  "name": "projects/my-project/operations/<operation-id>",
  "done": false
}

使用 GetOperation 轮询完成情况：

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Project, ProjectSpec

w = WorkspaceClient()

# Start an operation
operation = w.postgres.create_project(
    project=Project(spec=ProjectSpec(pg_version=17)),
    project_id="my-project",
)

# Wait for completion
result = operation.wait()
print(f"Operation completed: {result.name}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Start an operation
CreateProjectOperation operation = w.postgres().createProject(
    new CreateProjectRequest()
        .setProjectId("my-project")
        .setProject(new Project()
            .setSpec(new ProjectSpec()
                .setPgVersion(17L)))
);

// Wait for completion
Project result = operation.waitForCompletion();
System.out.println("Operation completed: " + result.getName());

CLI

默认情况下，CLI 会自动等待操作完成。使用 --no-wait 来立即返回。

databricks postgres create-project my-project --no-wait \
  --json '{"spec": {"pg_version": 17}}'

curl

# Poll the operation
curl "$WORKSPACE/api/2.0/postgres/projects/my-project/operations/<operation-id>" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq '.done'

每隔几秒钟轮询一次，直到 done 是 true。

更新掩码

更新作需要一个 update_mask 参数，用于指定要修改的字段。这可以防止意外覆盖非相关字段。

格式差异：

方法	Format	Example
REST API	查询参数	`?update_mask=spec.display_name`
Python SDK	FieldMask 对象	`update_mask=FieldMask(field_mask=["spec.display_name"])`
CLI	位置参数	`update-project NAME spec.display_name`

错误处理

Lakebase API 返回标准 HTTP 状态代码。

409：冲突操作

Lakebase 可能会出于多种原因返回 409 Conflict 错误：

项目正在进行内部维护操作。
该项目已达到并发操作限制。
你自己的 API 请求重叠。例如，在上一分支创建完成之前创建分支。

含义：

Lakebase 有时会计划对项目执行维护操作。如果在其中一项操作正在进行时收到客户端请求，Lakebase 将会拒绝新请求并返回409 Conflict错误。当项目达到容量上限或 API 调用重叠时，您可能会收到该响应。

这是预期的行为。客户端应准备好在发生此错误时重试请求。

操作方法：

重试请求。当内部操作完成或容量释放时，Lakebase 接受项目的新请求。

对重试使用指数退避：在第一次重试之前等待短间隔，然后在每次后续尝试时加倍等待。最多 30 秒的起始间隔为 100 毫秒，这是合理的默认值。

Python SDK

import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.errors import ResourceConflict
from databricks.sdk.service.postgres import Branch, BranchSpec

w = WorkspaceClient()

def retry_on_conflict(fn, max_attempts=5, base_delay=0.1):
    """Retry a Lakebase API call when a conflicting operation is in progress."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except ResourceConflict:
            if attempt == max_attempts - 1:
                raise
            wait = base_delay * (2 ** attempt)
            print(f"Conflicting operation in progress. Retrying in {wait}s...")
            time.sleep(wait)

# Example: create a branch with retry
branch = retry_on_conflict(
    lambda: w.postgres.create_branch(
        parent="projects/my-project",
        branch=Branch(spec=BranchSpec(no_expiry=True)),
        branch_id="my-branch",
    ).wait()
)

curl

# Retry with exponential backoff on 409 responses
retry_on_conflict() {
  local cmd=("$@")
  local max_attempts=5
  local delay=0.1
  local attempt=0

  while [ $attempt -lt $max_attempts ]; do
    response=$(curl -s -w "\n%{http_code}" "${cmd[@]}")
    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -ne 409 ]; then
      echo "$body"
      return 0
    fi

    attempt=$((attempt + 1))
    if [ $attempt -eq $max_attempts ]; then
      echo "Max retries reached. Last response: $body" >&2
      return 1
    fi

    echo "Conflicting operation in progress. Retrying in ${delay}s..." >&2
    sleep "$delay"
    delay=$((delay * 2))
  done
}

# Example: create a branch with retry
retry_on_conflict \
  -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches?branch_id=my-branch" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"no_expiry": true}}'

注释

在 Lakebase API 请求上出现 409 Conflict 意味着该请求未被接受，而不是请求已被应用。通过调用相应的 GET 终结点，始终在成功重试后验证资源状态。

SDK 和基础结构即代码

反馈

此页面是否有帮助？

Last updated on 2026-08-21

Lakebase API 指南

Authentication

设置身份验证

Python SDK

Java SDK

CLI

curl

可用端点

项目

分支

端点（计算实例和读取副本）

可用操作

角色

目录

同步表

变更数据流

数据库凭据

操作

权限

获取操作

Python SDK

Java SDK

CLI

curl

常见模式

资源命名

长期运行的操作 (LRO)

Python SDK

Java SDK

CLI

curl

更新掩码

错误处理

409：冲突操作

Python SDK

curl

SDK 和基础结构即代码

反馈

其他资源