创建项目时,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
- 在 “角色和数据库>添加角色>OAuth ”选项卡中,选择要授予数据库访问权限的用户、服务主体或组。
- 创建角色后,授予适当的数据库权限。 了解如何: 管理权限
SQL
先修条件:
- 你必须对数据库拥有
CREATE和CREATE ROLE权限 - 您必须使用有效的 OAuth 令牌对 Azure Databricks 身份进行认证。
- 本机 Postgres 经过身份验证的用户会话无法创建 OAuth 角色
创建
databricks_auth扩展。 每个 Postgres 数据库必须有自己的扩展。CREATE EXTENSION IF NOT EXISTS databricks_auth;使用
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 中管理权限,而不是维护单个用户的权限。
向新创建的角色授予数据库权限。
该 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 进行身份验证,从而简化权限管理。
工作原理:
- 为Azure Databricks组创建 Postgres 角色。
- 向 Postgres 中的组角色授予数据库权限。 请参阅 “管理权限”。
- Azure Databricks组的任何直接或间接成员(用户或服务主体)都可以使用其单独的 OAuth 令牌连接到 Postgres。
- 连接时,成员将作为组角色进行身份验证,并继承授予该角色的所有权限。
认证流程:
组成员连接时,将组的 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
- 在“角色和数据库>添加角色>密码”选项卡中,输入角色名称,并选择性地授予
databricks_superuser或系统属性(CREATEDB、、CREATEROLEBYPASSRLS)。 - 复制生成的密码并将其安全地提供给用户。 不再显示。
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。
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
在 Lakebase 应用中,转到您分支的角色和数据库选项卡。
单击要删除的角色的菜单,然后选择“ 删除”。
在确认对话框中,可以选择启用 重新分配拥有的对象。
如果 Postgres 角色拥有表、视图或架构等数据库对象,则无法删除该角色。 启用后,将显示将所有权重新分配给下拉菜单。 在删除之前,选择将接收对象所有权的角色。 重新分配完成后,无法重新分配的对象(例如对要删除的角色的授予)会自动删除。 禁用后,如果角色拥有任何对象,则删除将失败。
单击“确认”。
删除角色是永久操作,无法撤销。
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 文档中的以下资源: