创建 Postgres 角色

创建项目时,Lakebase 会在项目中创建多个 Postgres 角色:

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

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

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

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

注释

Postgres 角色控制 数据库访问 (谁可以查询数据)。 有关 项目权限 (谁可以管理基础结构),请参阅 项目权限。 有关设置这两者的教程,请参阅 教程:授予项目和数据库对新用户的访问权限。

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

创建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. 创建角色后,授予适当的数据库权限。 了解如何: 管理权限

添加角色 — OAuth 选项卡

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 中管理组级权限比管理单个用户权限更高效。 向组角色授予权限时,所有当前和将来的组成员都会自动继承这些权限。
  • 身份重命名:如果用户的邮箱或群组显示名称在 Azure Databricks 中发生变化,认证和现有数据库授权就会中断。 删除旧角色,创建具有更新名称的新角色,并更新连接字符串和授予。

注释

角色名称不能超过 63 个字符,不允许某些名称。 了解详细信息: 管理角色

创建一个原生的 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 以创建密码角色。 操作返回create_roleRole一个没有密码字段的对象。 SDK不会返回生成的密码。 要获得可用的密码,请参见 “获取密码”。

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 以创建密码角色。 该命令返回 Role 一个没有密码字段的对象。 CLI不会返回生成的密码。 要获得可用的密码,请参见 “获取密码”。

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 为止。 操作结果是一个 Role 没有密码字段的对象。 API 不会返回生成的密码。 要获得可用的密码,请参见 “获取密码”。

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 密码角色以及用户和服务主体的 OAuth 角色支持内置的连接池程序。 请参阅 “使用连接池”。

如何获取密码

Python SDK、REST API 和 CLI 创建角色操作不会返回生成的密码。 请使用以下方法之一获取本地 Postgres 密码角色的密码:

  • 在创建时通过 SQL 自行设置密码: 在 OAuth SQL 连接上运行 CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';。 这需要 CREATEROLE 特权。 请查看 创建本地 Postgres 密码角色下的 SQL 标签。
  • 在界面中重置密码:对于使用 Python SDK、REST API、CLI 或 Terraform 创建的角色,请使用 Lakebase 应用中的重置密码流程生成新密码。 参见 “重置密码”。

注释

使用 Python SDK、REST API 或 Terraform 创建的角色归内部控制平面角色所有。 客户主体不能用SQL更改这些角色的密码,因为Postgres 16要求角色有 ADMIN 更改密码的选项。 改用界面 重置密码 流程。

本地密码角色的存储方式

无论你如何创建 Postgres 原生密码角色,其密码都绝不会以明文形式存储。 计算节点的 Postgres 核心存储一个 SCRAM-SHA-256 验证器,服务器端计算(计算默认为 password_encryption = scram-sha-256)。 当 Lakebase 为你生成密码(UI、Python SDK、REST API 和 CLI 路径)时,控制平面还会保留经过 KMS 加密的凭证副本,这也是 UI 之后显示或重置密码的原因。 通过 SQL 设置的密码不会以这种方式保留:只会存储验证器。

  • 用户界面:Azure Databricks 在服务器端生成密码,计算验证器,并显示生成的密码一次。 那就把它复制下来吧,因为之后将不再显示。
  • Python SDK、REST API 和 CLI:Azure Databricks 在服务器端生成密码并计算验证器,但不会在响应中返回密码。 要获得可用的密码,可以在创建时使用SQL或 UI重置密码 流程。 参见 如何获取密码。 这些路径不接受你提供的密码。
  • SQL: 运行 CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';(或 psql 的 \password)时,你提供明文,服务器会将其哈希生成验证器。

你永远不需要自己对密码进行哈希处理。

查看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 更新角色的系统角色或属性。 只有更新掩码中所指定的字段会发生更改。

spec.identity_type、spec.auth_method 和 spec.postgres_role 在创建后无法更改。

在 update_mask 中选中时,spec.membership_roles 将替换所有现有成员资格。 空列表或省略列表将清除所有成员资格,包括 DATABRICKS_SUPERUSER。

注释

使用由name返回的资源来更新或删除角色。 role_id 表示 API 资源,spec.postgres_role 表示 Postgres 角色名称。

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

  1. 在 Lakebase 应用中,转到您分支的角色和数据库选项卡。

  2. 单击要删除的角色的菜单,然后选择“ 删除”。

  3. 在确认对话框中,可以选择启用 重新分配拥有的对象。

    如果 Postgres 角色拥有表、视图或架构等数据库对象,则无法删除该角色。 启用后,将显示将所有权重新分配给下拉菜单。 在删除之前,选择将接收对象所有权的角色。 重新分配完成后,无法重新分配的对象(例如对要删除的角色的授予)会自动删除。 禁用后,如果角色拥有任何对象,则删除将失败。

  4. 单击“确认”。

删除角色是永久操作,无法撤销。

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 角色。

角色 Description 继承的权限
<project_owner_role> 项目创建者的 Azure Databricks 标识(例如 my.user@databricks.com)。 此角色拥有默认 databricks_postgres 数据库,可以登录和管理项目。 成员 databricks_superuser
databricks_superuser 内部管理角色。 用于配置和管理跨项目的访问权限。 此角色被授予广泛的特权。 继承自pg_read_all_data、pg_write_all_data和pg_monitor。

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

Azure Databricks 创建的系统角色

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

角色 目的
cloud_admin 用于云基础结构管理的超级用户角色
databricks_control_plane 内部 Databricks 组件用于管理操作的超级用户角色
databricks_monitor 用于内部指标收集服务
databricks_replicator 用于数据库复制操作
databricks_writer_<dbid> 用于管理和创建同步表的数据库专用角色
databricks_reader_<dbid> 每个数据库角色用于读取注册在 Unity Catalog 中的表
databricks_gateway 用于托管数据服务服务的内部连接

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

其他资源