建立 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 使用者介面、databricks_auth 包含 SQL 的擴充功能，或是利用 Python SDK 和 REST API 來建立這些角色。啟用 Azure Databricks 身份（使用者、服務主體及群組）使用 OAuth 令牌連接。
Native Postgres 密碼角色： 使用 Lakebase 介面、SQL、Python SDK 和 REST API 來建立這些角色。使用任何有效的角色名稱並使用密碼驗證。

關於選擇角色類型，請參閱認證概述。每個平台都有不同的使用情境設計。

為 Azure Databricks 身分識別建立 OAuth 角色

若要讓 Azure Databricks 身份（使用者、服務主體或群組）使用 OAuth 標記連接，請使用 Lakebase UI、 databricks_auth 包含 SQL 的擴充功能或 REST API 建立 OAuth 角色。

關於取得 OAuth 標記的詳細說明，請參閱「在使用者對機器流程中取得 OAuth 標記」及「在機器對機器流程中取得 OAuth 標記」。

UI

在 「角色與資料庫新增>角色>OAuth 標籤」中，選擇使用者、服務主體或群組以授權資料庫存取權。
建立角色後，授予適當的資料庫權限。了解如何管理權限

新增角色 — OAuth 標籤

SQL

先決條件：

你必須擁有CREATECREATE 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() 授權來建立 Postgres 角色。建立角色後，您必須對使用者需要存取的特定資料庫、結構或資料表授予適當的資料庫權限與權限。了解如何管理權限

Python SDK

設定 identity_type 為 USER、 SERVICE_PRINCIPAL、或 GROUP。分別設定 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

對於 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 (Unix指令)

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， CREATEROLE， BYPASSRLS）。
複製產生的密碼並安全地提供給使用者。此段之後未再播出。

新增角色 — 密碼標籤

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

密碼必須至少包含12個字元，包含小寫、大寫、數字和符號等字元。使用者自訂密碼在建立時會被驗證以驗證 60 位元熵。

Python SDK

以省略 identity_type 建立密碼角色。 create_role 操作會回傳不含密碼欄位的 Role 物件。 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 (Unix指令)

以省略 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 密碼角色支援內建的連線池。請參閱使用連線池。

如何取得密碼

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 App 中的重設密碼流程來產生新密碼。請參見「重設密碼」。

備註

使用 Python SDK、REST API 或 Terraform 建立的角色，歸內部的控制平面角色所擁有。客戶主體無法用 SQL 更改這些角色的密碼，因為 Postgres 16 要求角色有 ADMIN 更改密碼的選項。改用 UI 重設密碼 流程。

原生密碼角色的儲存方式

無論你如何建立原生 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 App 中分支機構的「 角色與資料庫」 分頁。分支中建立的所有角色（系統角色除外）都會列出。 Auth type 欄位顯示每個角色使用 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 (Unix指令)

列出所有職務：

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 來更新角色的系統角色或屬性。只有更新遮罩中指定的欄位會改變。

備註

要取得角色的資源名稱用於更新與刪除呼叫，請使用 list roles 端點。角色資源名稱使用系統產生的識別碼（例如 rol-xxxx-xxxxxxxxxx），而非 postgres_role 建立時提供的值。

CLI

使用 update mask 模式來更新角色。更新遮罩是資源名稱之後的第二個位置參數。

更新 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 (Unix指令)

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": []。

刪除一個PostgreSQL角色

你可以同時移除 Azure Databricks 的身份基礎角色和內建的 Postgres 密碼角色。

UI

請前往 Lakebase App 中你分行的角色 與資料庫 分頁。
點選你想丟棄的角色選單，然後選擇 「放棄」。
在確認對話框中，可視需要啟用 重新指派所擁有的物件。

如果 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 (Unix指令)

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 角色，用於專案管理和啟動。

Role	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指令來查看這些角色。

Role	目標
`cloud_admin`	用於雲端基礎架構管理的超級使用者角色
`databricks_control_plane`	內部 Databricks 元件用於管理操作的超級使用者角色
`databricks_monitor`	由內部計量收集服務使用
`databricks_replicator`	用於資料庫複製操作
`databricks_writer_<dbid>`	在每個資料庫中用來建立和管理同步處理資料表的角色
`databricks_reader_<dbid>`	用來讀取 Unity 目錄中註冊資料表的每個資料庫角色
`databricks_gateway`	用於管理數據服務的內部連接

若要了解角色、權限和角色成員資格在 Postgres 中的運作方式，請使用 Postgres 文件中的下列資源：

其他資源

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-18