创建 Postgres 角色

创建项目时，Lakebase 会在项目中创建多个 Postgres 角色：

• 项目所有者的 Azure Databricks 标识（例如 user@databricks.com）对应的 Postgres 角色，该角色拥有默认的 databricks_postgres 数据库。
• 管理 databricks_superuser 角色

首次打开项目时，这两个角色在“ 角色和数据库 ”选项卡中可见。

数据库 databricks_postgres 已创建，因此可以在创建项目后立即连接并试用 Lakebase。

还会创建多个系统管理角色。 这些内部角色由 Azure Databricks 服务用于管理、监控和数据操作。

请参阅 预创建的角色 和 系统角色。

创建 Postgres 角色

Lakebase 支持两种类型的 Postgres 角色进行数据库访问：

• Azure Databricks 标识的 OAuth 角色： 可以使用 Lakebase UI、databricks_auth SQL 扩展，或使用 Python SDK 和 REST API 来创建它们。 允许 Azure Databricks 标识（用户、服务主体和组）使用 OAuth 令牌进行连接。
• 本机 Postgres 密码角色： 使用 Lakebase UI、SQL 或 Python SDK 和 REST API 创建它们。 将任何有效的角色名称用于密码身份验证。

有关选择要使用的角色类型的指南，请参阅 身份验证概述。 每个方案都针对不同的用例而设计。

为 Azure Databricks 标识创建 OAuth 角色

若要允许 Azure Databricks 标识（用户、服务主体或组）使用 OAuth 令牌进行连接，请使用 Lakebase UI、 databricks_auth SQL 扩展或 REST API 创建 OAuth 角色。

有关获取 OAuth 令牌的详细说明，请参阅 在用户到计算机流中获取 OAuth 令牌 ，并在 计算机到计算机流中获取 OAuth 令牌。

UI

1. 在 “角色和数据库>添加角色>OAuth ”选项卡中，选择要授予数据库访问权限的用户、服务主体或组。
2. 创建角色后，授予适当的数据库权限。 了解如何： 管理权限

SQL

先决条件：

• 你必须对数据库拥有 CREATE 和 CREATE ROLE 权限
• 您必须使用有效的 OAuth 令牌对 Azure Databricks 身份进行认证。
• 本机 Postgres 经过身份验证的用户会话无法创建 OAuth 角色

1. 创建databricks_auth扩展。 每个 Postgres 数据库必须有自己的扩展。

   CREATE EXTENSION IF NOT EXISTS databricks_auth;
   

2. 使用 databricks_create_role 函数为 Azure Databricks 标识创建 Postgres 角色：

   SELECT databricks_create_role('identity_name', 'identity_type');
   

   对于 Azure Databricks 用户：

   SELECT databricks_create_role('myuser@databricks.com', 'USER');
   

   对于 Azure Databricks 服务主体：

   SELECT databricks_create_role('8c01cfb1-62c9-4a09-88a8-e195f4b01b08', 'SERVICE_PRINCIPAL');
   

   对于 Azure Databricks 组：

   SELECT databricks_create_role('My Group Name', 'GROUP');
   

   组名称区分大小写，必须与 Azure Databricks 工作区中显示的组名称完全匹配。 为组创建 Postgres 角色时，Databricks 组的任何直接或间接成员（用户或服务主体）都可以使用其单个 OAuth 令牌向 Postgres 进行身份验证作为组角色。 此组级权限模型允许你在 Postgres 中管理权限，而不是维护单个用户的权限。

3. 向新创建的角色授予数据库权限。

该 databricks_create_role() 函数仅创建具有权限的 LOGIN Postgres 角色。 创建角色后，必须授予用户访问的特定数据库、架构或表的相应数据库特权和权限。 了解如何： 管理权限

Python SDK

设置为identity_typeUSER或 SERVICE_PRINCIPALGROUP。 请分别将 postgres_role 设置为标识所对应的电子邮件地址、应用程序 ID（UUID）或组显示名称。 此值将成为 Postgres 角色名称，是连接字符串和 GRANT 语句中使用的名称。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleIdentityType, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            identity_type=RoleIdentityType.USER,
            postgres_role="user@example.com"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

创建角色后，授予适当的数据库权限。 了解如何： 管理权限

CLI

设置为identity_typeUSER或 SERVICE_PRINCIPALGROUP。 请分别将 postgres_role 设置为标识所对应的电子邮件地址、应用程序 ID（UUID）或组显示名称。 此值将成为 Postgres 角色名称，是连接字符串和 GRANT 语句中使用的名称。

对于 Azure Databricks 用户：

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

对于 Azure Databricks 服务主体：

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "8c01cfb1-62c9-4a09-88a8-e195f4b01b08"}}'

对于 Azure Databricks 组：

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-group-role \
  --json '{"spec": {"identity_type": "GROUP", "postgres_role": "My Group Name"}}'

该命令等待操作完成并返回已创建的角色。 使用--no-wait立即返回，并使用databricks postgres get-operation进行单独轮询。

创建角色后，授予适当的数据库权限。 了解如何： 管理权限

curl

设置为identity_typeUSER或 SERVICE_PRINCIPALGROUP。 请分别将 postgres_role 设置为标识所对应的电子邮件地址、应用程序 ID（UUID）或组显示名称。 此值将成为 Postgres 角色名称，是连接字符串和 GRANT 语句中使用的名称。

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "identity_type": "USER",
      "postgres_role": "user@example.com"
    }
  }' | jq

端点返回长时间运行的操作。 轮询直到done变为true，然后使用角色的name字段进行后续 API 调用。 请参阅 长时间运行的操作。

创建角色后，授予适当的数据库权限。 了解如何： 管理权限

基于组的身份验证

为 Azure Databricks 组创建 Postgres 角色时，启用基于组的身份验证。 这样，Azure Databricks 组的任何成员就可以使用组的角色向 Postgres 进行身份验证，从而简化权限管理。

工作原理：

1. 为Azure Databricks组创建 Postgres 角色。
2. 向 Postgres 中的组角色授予数据库权限。 请参阅 “管理权限”。
3. Azure Databricks组的任何直接或间接成员（用户或服务主体）都可以使用其单独的 OAuth 令牌连接到 Postgres。
4. 连接时，成员将作为组角色进行身份验证，并继承授予该角色的所有权限。

身份验证流：

组成员连接时，将组的 Postgres 角色名称指定为用户名，并将自己的 OAuth 令牌指定为密码：

export PGPASSWORD='<OAuth token of a group member>'
export GROUP_ROLE_NAME='<pg-case-sensitive-group-role-name>'

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUP_ROLE_NAME

重要注意事项：

• 组成员身份验证： 仅在身份验证时验证组成员身份。 如果在建立连接后从 Azure Databricks 组中删除了成员，则连接将保持活动状态。 已删除成员的连接尝试将被拒绝。
• 工作区范围： 仅支持在与项目相同的 Azure Databricks 工作区中分配的组进行基于组的认证。 若要了解如何将组分配到工作区，请参阅 “管理组”。
• 区分大小写： 您在 databricks_create_role() 使用的组名称必须与 Azure Databricks 工作区中显示的组名称完全一致，包括大小写。
• 权限管理： 在 Postgres 中的组级别管理权限比管理单个用户权限更有效。 向组角色授予权限时，所有当前和将来的组成员都会自动继承这些权限。
• Identity 重命名： 如果用户的电子邮件或组显示名称在Azure Databricks更改，身份验证和现有数据库权限将会中断。 删除旧角色，创建具有更新名称的新角色，并更新连接字符串和授予。

创建本地 Postgres 密码角色

可以在项目或计算级别禁用密码连接。 请参阅 “阻止密码连接”。

UI

1. 在“角色和数据库>添加角色>密码”选项卡中，输入角色名称，并选择性地授予databricks_superuser或系统属性（CREATEDB、、CREATEROLEBYPASSRLS）。
2. 复制生成的密码并将其安全地提供给用户。 不再显示。

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

密码必须至少有 12 个字符，并且混合使用小写、大写、数字和符号字符。 在创建时对用户定义的密码进行验证，以确保密码具有 60 位熵。

Python SDK

省略 identity_type 以创建密码角色。 API 在响应中返回生成的密码。

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            postgres_role="my-app-role"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

CLI

省略 identity_type 以创建密码角色。 API 将生成密码，并在响应中返回密码。

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

该命令等待操作完成。 响应包括生成的密码 - 安全地保存，因为它不会再次显示。

curl

省略 identity_type 以创建密码角色。 端点返回长时间运行的操作。 投票直到 done 是 true。

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_role": "my-app-role"
    }
  }' | jq

查看 Postgres 角色

UI

若要查看项目中的所有 Postgres 角色，请导航到 Lakebase 应用中分支的角色 和数据库 选项卡。 在分支中创建的所有角色（系统 角色除外）都会列出。 身份验证类型列指示每个角色是使用 OAuth 还是密码身份验证。

PostgreSQL

使用 \du 命令查看所有角色：

可以使用任何 Postgres 客户端（例如）或 Lakebase SQL 编辑器中的元命令查看所有 Postgres 角色，包括\dupsql：

\du
                                      List of roles
          Role name          |                         Attributes
-----------------------------+------------------------------------------------------------
 cloud_admin                 | Superuser, Create role, Create DB, Replication, Bypass RLS
 my.user@databricks.com      | Create role, Create DB, Bypass RLS
 databricks_control_plane    | Superuser
 databricks_gateway          |
 databricks_monitor          |
 databricks_reader_12345     | Create role, Create DB, Replication, Bypass RLS
 databricks_replicator       | Replication
 databricks_superuser        | Create role, Create DB, Cannot login, Bypass RLS
 databricks_writer_12345     | Create role, Create DB, Replication, Bypass RLS

Python SDK

列出所有角色：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

roles = w.postgres.list_roles(parent="projects/my-project/branches/production")
for role in roles:
    print(f"{role.status.postgres_role} ({role.status.identity_type or 'PASSWORD'}): {role.name}")

获取特定角色：

role = w.postgres.get_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
print(role)

CLI

列出所有角色：

databricks postgres list-roles projects/my-project/branches/production

获取特定角色：

databricks postgres get-role projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

输出包括用于更新和删除调用所需的字段name（例如 rol-xxxx-xxxxxxxxxx）。

curl

列出所有角色：

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

获取特定角色：

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

响应包括更新和删除调用所需的 name 字段（例如 rol-xxxx-xxxxxxxxxx）。

更新角色

若要在 UI 中更新角色的属性，请从“角色和数据库”选项卡中的角色菜单中选择“编辑角色”。

使用 API 或 CLI 更新角色的系统角色或属性。 只有更新掩码中所指定的字段会发生更改。

CLI

使用更新掩码模式更新角色。 更新掩码是资源名称后的第二个位置参数。

更新 spec.attributes时，必须提供所有三个属性字段 （createdb， createrole， bypassrls） — API 将替换整个属性对象：

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.attributes" \
  --json '{
    "spec": {
      "attributes": {"createdb": true, "createrole": false, "bypassrls": false}
    }
  }'

若要同时更新成员身份角色，请将 spec.membership_roles 添加到更新掩码中：

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.membership_roles" \
  --json '{"spec": {"membership_roles": ["DATABRICKS_SUPERUSER"]}}'

若要删除databricks_superuser，请传递空数组： "membership_roles": []

curl

curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx?update_mask=spec.membership_roles%2Cspec.attributes.createdb" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx",
    "spec": {
      "membership_roles": ["DATABRICKS_SUPERUSER"],
      "attributes": { "createdb": true }
    }
  }' | jq

若要删除databricks_superuser，请传递空数组： "membership_roles": []

删除 Postgres 角色

可以删除基于标识的 Azure Databricks 角色和内置的 Postgres 密码角色。

UI

删除角色是一项无法撤销的永久操作。 若要删除拥有数据库的角色，必须指定要将拥有的对象重新分配到的角色。 否则，必须先手动删除数据库，然后再删除拥有该数据库的角色。

若要使用 UI 删除任何 Postgres 角色，请执行以下作：

1. 转到 Lakebase 应用中分支的角色 和数据库 选项卡。
2. 从 角色菜单中选择“删除角色 ”并确认删除。

PostgreSQL

可以使用标准 Postgres 命令删除任何 Postgres 角色。 有关详细信息，请参阅 有关删除角色的 PostgreSQL 文档。

删除角色：

DROP ROLE role_name;

删除基于 Azure Databricks 标识的角色后，在创建新角色之前，该标识将无法再使用 OAuth 令牌向 Postgres 进行身份验证。

CLI

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

如果该角色拥有数据库对象，则用于 --reassign-owned-to 在删除之前将所有权转移到另一个角色：

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  --reassign-owned-to projects/my-project/branches/production/roles/rol-yyyy-yyyyyyyyyy

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.delete_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
operation.wait()

curl

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

预先创建的角色

创建项目后，Azure Databricks 会自动为项目管理和入门创建 Postgres 角色。

详细了解这些角色的特定功能和特权： 预先创建的角色功能

Azure Databricks 创建的系统角色

Azure Databricks 创建内部服务所需的以下系统角色。 可以通过从\du或psql发出命令来查看这些角色。

若要了解角色、特权和角色成员身份在 Postgres 中的工作原理，请使用 Postgres 文档中的以下资源：

• 数据库角色
• 特权

后续步骤

• 管理权限
• 连接到项目
• 了解身份验证