建立及管理使用者

本頁面說明如何啟用並使用 Cloud SQL 內建驗證機制。

如需總覽，請參閱「Cloud SQL 內建資料庫驗證機制」。

建立使用者前

  1. 建立 Cloud SQL 執行個體。詳情請參閱「建立執行個體」。
  2. 啟用執行個體的密碼政策。詳情請參閱「執行個體密碼政策」。

  3. 如果您打算使用資料庫的管理用戶端管理使用者，請按照下列步驟操作：

    1. 將用戶端連線至執行個體。請參閱「外部應用程式的連線選項」。

    2. 設定密碼，在執行個體上設定預設使用者。請參閱「設定預設使用者帳戶的密碼」。

設定預設使用者帳戶的密碼

建立新的 Cloud SQL 執行個體時，必須先為預設使用者帳戶設定密碼，才能連線至執行個體。

如果是 PostgreSQL 適用的 Cloud SQL，預設使用者為 postgres。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 找到 postgres 使用者，然後在「更多動作」選單 更多動作圖示。 中選取「變更密碼」。
  5. 輸入您記得住的高強度密碼，然後按一下「OK」(確定)。

gcloud

使用下列 gcloud sql users set-password 指令，設定預設使用者的密碼。

請先將 INSTANCE_NAME 替換為執行個體名稱，再執行指令。

gcloud sql users set-password postgres \
--instance=INSTANCE_NAME \
--prompt-for-password

REST v1

如要更新預設使用者帳戶的密碼，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID
  • user-id：使用者 ID
  • password：使用者的密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/users?name=user-id

JSON 要求主體：

{
  "name": "user-id",
  "password": "password"
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "UPDATE_USER",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

REST v1beta4

如要更新預設使用者帳戶的密碼，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID
  • user-id：使用者 ID
  • password：使用者的密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users?name=user-id

JSON 要求主體：

{
  "name": "user-id",
  "password": "password"
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "UPDATE_USER",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

新增使用者

設定預設使用者帳戶後，即可建立其他使用者。

建立內建使用者時，您可以為使用者指派一或多個資料庫角色。

如要將自訂資料庫角色指派給使用者，您必須先在 PostgreSQL 資料庫中建立角色。如要在 PostgreSQL 中建立角色，請參閱「資料庫角色」。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 按一下「Add user account」(新增使用者帳戶)。

    在「Add a user account to instance instance_name」(將使用者帳戶新增至執行個體 instance_name)instance_name 頁面中，您可以選擇使用者要透過內建資料庫方法 (使用者名稱和密碼) 進行驗證，還是以 IAM 使用者身分進行驗證。

  5. 選取「內建驗證」(預設)，然後新增下列資訊：
    • 「User name」(使用者名稱)。
    • 選用。密碼。設定您記得住的高強度密碼。
  6. 按一下「新增」。

如果您建立的 PostgreSQL 使用者採用內建驗證機制，系統會自動將 cloudsqlsuperuser 角色授予該使用者。使用者會獲得與這個角色相關聯的下列權限：CREATEROLE、CREATEDB 和 LOGIN。

如要變更使用者的權限，可以在 Cloud SQL 中建立使用者時，建立並指派一或多個自訂 PostgreSQL 資料庫角色。如果在 Cloud SQL 中建立使用者時，指派一或多個自訂資料庫角色，則使用者不會獲得 cloudsqlsuperuser 角色。

如要變更這些使用者的屬性，請在 psql 用戶端中使用 ALTER ROLE 指令。並非所有屬性都能使用 ALTER ROLE 修改。NOSUPERUSER 和 NOREPLICATION 角色不在此限。

如要進一步瞭解這些使用者帳戶和權限，請參閱「其他 PostgreSQL 使用者帳戶」。

gcloud

如要建立使用者，請使用 gcloud sql users create 指令。

更改下列內容：

  • USER_NAME：使用者名稱。
  • INSTANCE_NAME：執行個體的名稱。
  • PASSWORD：使用者的密碼。
  • ROLE_1、ROLE_2...、ROLE_N：選用。要指派給使用者的資料庫角色。
gcloud sql users create USER_NAME \
--instance=INSTANCE_NAME \
--password=PASSWORD \
--database-roles=ROLE_1, ROLE_2, ..., ROLE_N

如果您建立的 PostgreSQL 使用者採用內建驗證機制，系統會自動將 cloudsqlsuperuser 角色授予該使用者。使用者會獲得與這個角色相關聯的下列權限：CREATEROLE、CREATEDB 和 LOGIN。

如要變更使用者的權限，可以在 Cloud SQL 中建立使用者時，建立並指派一或多個自訂 PostgreSQL 資料庫角色。如果在 Cloud SQL 中建立使用者時，指派一或多個自訂資料庫角色，則使用者不會獲得 cloudsqlsuperuser 角色。

如要變更這些使用者的屬性，請在 psql 用戶端中使用 ALTER ROLE 指令。並非所有屬性都能使用 ALTER ROLE 修改。NOSUPERUSER 和 NOREPLICATION 角色不在此限。

如要進一步瞭解這些使用者帳戶和權限，請參閱「其他 PostgreSQL 使用者帳戶」。

Cloud SQL 的使用者名稱長度限制與地端部署 PostgreSQL 相同。

建立使用者時，您可以新增使用者密碼政策參數。

Terraform

如要建立使用者，請使用 Terraform 資源。

resource "random_password" "pwd" {
  length  = 16
  special = false
}

resource "google_sql_user" "user" {
  name     = "user"
  instance = google_sql_database_instance.default.name
  password = random_password.pwd.result
}

您也可以建立使用者並指派資料庫角色。

resource "google_sql_user" "builtin_user" {
  name     = "test-user1"
  password = "password"
  instance = google_sql_database_instance.default.name
  # Specify the list of database roles to be granted to the user
  # The database roles must exist in the database.
  database_roles = ["cloudsqlsuperuser"]
}

套用變更

如要在 Cloud de Confiance 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

  1. 啟動 Cloud Shell。

  2. 設定要套用 Terraform 設定的預設 Cloud de Confiance 專案。

    這項指令在每個專案中只需執行一次，且可在任何目錄中執行。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為「根模組」)。

  1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. 如果您正在按照教學課程操作，可以複製每個章節或步驟中的程式碼範例。

    將程式碼範例複製到新建立的 main.tf。

    您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

  3. 請查看並修改範例參數，以便套用至您的環境。
  4. 儲存變更。
  5. 初始化 Terraform。每個目錄只需執行一次這項操作。 
    terraform init

    如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：

    terraform init -upgrade

套用變更

  1. 查看設定，確認 Terraform 要建立或更新的資源符合預期：
    terraform plan

    視需要修正設定。

  2. 執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：
    terraform apply

    等待 Terraform 顯示「Apply complete!」訊息。

  3. 開啟 Cloud de Confiance 專案即可查看結果。在 Cloud de Confiance 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

如要刪除變更，請按照下列步驟操作：

  1. 如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
    deletion_protection =  "false"
  2. 執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定： 
    terraform apply

  1. 執行下列指令，並在提示中輸入 yes，移除先前使用 Terraform 設定套用的資源：

    terraform destroy

REST v1

如要建立使用者，請使用 POST 要求和 users:insert 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼
  • ROLE_1、ROLE_2...、ROLE_N：選用。要指派給使用者的資料庫角色

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

如果您建立的 PostgreSQL 使用者採用內建驗證機制，系統會自動將 cloudsqlsuperuser 角色授予該使用者。使用者會獲得與這個角色相關聯的下列權限：CREATEROLE、CREATEDB 和 LOGIN。

如要變更使用者的權限，可以在 Cloud SQL 中建立使用者時，建立並指派一或多個自訂 PostgreSQL 資料庫角色。如果在 Cloud SQL 中建立使用者時，指派一或多個自訂資料庫角色，則使用者不會獲得 cloudsqlsuperuser 角色。

如要變更這些使用者的屬性，請在 psql 用戶端中使用 ALTER ROLE 指令。並非所有屬性都能使用 ALTER ROLE 修改。NOSUPERUSER 和 NOREPLICATION 角色不在此限。

如要進一步瞭解這些使用者帳戶和權限，請參閱「其他 PostgreSQL 使用者帳戶」。

Cloud SQL 的使用者名稱長度限制與地端部署 PostgreSQL 相同。

建立使用者時，您可以新增使用者密碼政策參數。

REST v1beta4

如要建立使用者，請使用 POST 要求和 users:insert 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼
  • ROLE_1、ROLE_2...、ROLE_N：選用。要指派給使用者的資料庫角色

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "databaseRoles": [
    "ROLE_1",
    "ROLE_2"
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "CREATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

如果您建立的 PostgreSQL 使用者採用內建驗證機制，系統會自動將 cloudsqlsuperuser 角色授予該使用者。使用者會獲得與這個角色相關聯的下列權限：CREATEROLE、CREATEDB 和 LOGIN。

如要變更使用者的權限，可以在 Cloud SQL 中建立使用者時，建立並指派一或多個自訂 PostgreSQL 資料庫角色。如果在 Cloud SQL 中建立使用者時，指派一或多個自訂資料庫角色，則使用者不會獲得 cloudsqlsuperuser 角色。

如要變更這些使用者的屬性，請在 psql 用戶端中使用 ALTER ROLE 指令。並非所有屬性都能使用 ALTER ROLE 修改。NOSUPERUSER 和 NOREPLICATION 角色不在此限。

如要進一步瞭解這些使用者帳戶和權限，請參閱「其他 PostgreSQL 使用者帳戶」。

Cloud SQL 的使用者名稱長度限制與地端部署 PostgreSQL 相同。

建立使用者時，您可以新增使用者密碼政策參數。

psql 用戶端

  1. 在 psql 提示中建立使用者：
      CREATE USER USER_NAME
      WITH PASSWORD PASSWORD
      ATTRIBUTE1
      ATTRIBUTE2...;

    系統出現提示時，輸入密碼。

    如要進一步瞭解角色屬性，請參閱 PostgreSQL 說明文件。

  2. 您可以顯示使用者資料表，確認使用者是否建立成功：
      SELECT * FROM pg_roles;

設定使用者密碼政策

您可以使用內建驗證類型設定密碼政策。

gcloud

如要設定使用者密碼政策，請使用 gcloud sql users set-password-policy 指令。

更改下列內容：

  • USER_NAME：使用者名稱。
  • INSTANCE_NAME：執行個體的名稱。
  • HOST：使用者的主機名稱，可以是特定 IP 位址、位址範圍或任何主機 (%)。
  • PASSWORD_POLICY_ALLOWED_FAILED_ATTEMPTS：選用。使用者在帳戶鎖定前，可嘗試輸入錯誤密碼的次數。使用 --password-policy-enable-failed-attempts-check 啟用檢查，並使用 --no-password-policy-enable-failed-attempts-check 停用檢查。
  • PASSWORD_POLICY_PASSWORD_EXPIRATION_DURATION：選用。指定密碼失效的天數，屆時使用者必須建立新密碼。
gcloud sql users set-password-policy USER_NAME \
--instance=INSTANCE_NAME \
--host=HOST \
--password-policy-enable-failed-attempts-check \
--password-policy-allowed-failed-attempts=PASSWORD_POLICY_ALLOWED_FAILED_ATTEMPTS \
--password-policy-password-expiration-duration=PASSWORD_POLICY_PASSWORD_EXPIRATION_DURATION

如要移除使用者密碼政策，請使用 --clear-password-policy 參數。

gcloud sql users set-password-policy USER_NAME \
--instance=INSTANCE_NAME \
--host=HOST \
--clear-password-policy

如要查看使用者密碼政策，請參閱「列出使用者」。

REST v1

如要設定使用者密碼政策，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼
  • FAILED_ATTEMPTS_CHECK：設為 true，即可啟用檢查功能，在登入失敗次數達到上限後鎖定帳戶
  • NUMBER_OF_ATTEMPTS：登入失敗幾次後，帳戶會遭到鎖定
  • PASSWORD_EXPIRATION_DURATION：密碼到期後，使用者必須建立新密碼的天數

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?name=USER_ID

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "data":
  {
    "passwordValidationUserPolicy" : {
      {
        "enableFailedAttemptsCheck" : "FAILED_ATTEMPTS_CHECK",
        "allowedFailedAttempts" : "NUMBER_OF_ATTEMPTS",
        "passwordExpirationDuration" : "PASSWORD_EXPIRATION_DURATION"
      }
    },
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

如要查看使用者密碼政策，請參閱「列出使用者」。

REST v1beta4

如要設定使用者密碼政策，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼
  • FAILED_ATTEMPTS_CHECK：設為 true，即可啟用檢查功能，在登入失敗次數達到上限後鎖定帳戶
  • NUMBER_OF_ATTEMPTS：登入失敗幾次後，帳戶會遭到鎖定
  • PASSWORD_EXPIRATION_DURATION：密碼到期後，使用者必須建立新密碼的天數

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?name=USER_ID

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "data":
  {
    "passwordValidationUserPolicy" : {
      {
        "enableFailedAttemptsCheck" : "FAILED_ATTEMPTS_CHECK",
        "allowedFailedAttempts" : "NUMBER_OF_ATTEMPTS",
        "passwordExpirationDuration" : "PASSWORD_EXPIRATION_DURATION"
      }
    },
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

如要查看使用者密碼政策，請參閱「列出使用者」。

列出使用者

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。

gcloud

使用 gcloud sql users list 指令，列出這個執行個體的使用者：

gcloud sql users list \
--instance=INSTANCE_NAME

指令會傳回每位使用者的 Name、Host 和驗證 Type。

此外，如果是內建驗證類型，系統會傳回密碼政策設定和狀態。例如：

    NAME    HOST    TYPE        PASSWORD_POLICY
    user1           BUILT_IN    {'allowedFailedAttempts': 2,
                                 'enableFailedAttemptsCheck': True,
                                 'passwordExpirationDuration': '7d',
                                 'status': {
                                   'locked': True,
                                   'passwordExpirationTime': '2022-07-01T19:53:45.822742904Z'
                                 }
                                }

REST v1

如要列出為執行個體定義的使用者，請使用 GET 要求搭配 users:list 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID

HTTP 方法和網址：

GET https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/users

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#usersList",
  "items": [
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "sqlserver",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-1",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-2",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

如果已設定使用者密碼政策，回應的 items 區段會包含 passwordPolicy 區段。以下程式碼範例顯示 passwordPolicy 區段。

  {
  ...
  "passwordValidationUserPolicy" : {
    {
      "enableFailedAttemptsCheck" : true,
      "allowedFailedAttempts" : 8,
      "passwordExpirationDuration" : "7d"
    }
  },
  ...
}

REST v1beta4

如要列出為執行個體定義的使用者，請使用 GET 要求搭配 users:list 方法。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID

HTTP 方法和網址：

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#usersList",
  "items": [
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "sqlserver",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-1",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      "kind": "sql#user",
      "etag": "--redacted--",
      "name": "user-id-2",
      "host": "",
      "instance": "instance-id",
      "project": "project-id",
      "sqlserverUserDetails": {
        "serverRoles": [
          "CustomerDbRootRole"
        ]
      }
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

如果已設定使用者密碼政策，回應的 items 區段會包含 passwordPolicy 區段。以下程式碼範例顯示 passwordPolicy 區段。

  {
  ...
  "passwordValidationUserPolicy" : {
    {
      "enableFailedAttemptsCheck" : true,
      "allowedFailedAttempts" : 8,
      "passwordExpirationDuration" : "7d"
    }
  },
  ...
}

psql 用戶端

在 psql 提示字元中，列出 PostgreSQL 使用者：

SELECT * FROM pg_roles;

將資料庫角色新增至現有使用者

建立內建使用者後，您可以為使用者指派其他角色。這些角色會新增至現有角色，不會取代指派給使用者帳戶的現有角色。

您必須先建立角色，才能在 PostgreSQL 適用的 Cloud SQL 中將角色指派給使用者。如果您使用的是自訂角色，則必須先在 PostgreSQL 資料庫中建立角色。

如要在 PostgreSQL 中建立角色，請參閱「資料庫角色」。

除了 cloudsqlsuperuser 之外，您無法將「Cloud SQL 系統角色和使用者」中列出的任何預先定義系統角色指派給現有的 PostgreSQL 使用者。

gcloud

如要為使用者指派角色，請使用 gcloud sql users assign-roles 指令。

gcloud sql users assign-roles USER_NAME \
--instance=INSTANCE_NAME \
--type=BUILT_IN \
--database-roles=ROLE_1, ROLE_2, ..., ROLE_N

更改下列內容：

  • USER_NAME：使用者名稱。
  • INSTANCE_NAME：執行個體的名稱。
  • ROLE_1、ROLE_2、...、ROLE_N：要指派給使用者的資料庫角色。
在 type 欄位中，指定 BUILT_IN 來代表 Cloud SQL 使用者類型。這個欄位會決定驗證方法。

REST v1

如要更新使用者，請使用 users:update 方法傳送 PUT 要求。

指派資料庫角色時，您可以更新使用者密碼政策參數。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USER_ID：使用者 ID
  • ROLE_1、ROLE_2 ...、ROLE_N：要指派給使用者的資料庫角色
在 type 欄位中，指定 BUILT_IN 來代表 Cloud SQL 使用者類型。這個欄位會決定驗證方法。

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "type": "BUILT_IN",
  "databaseRoles": [
   "ROLE_1",
   "ROLE_2"
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "UPDATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

如要更新使用者，請使用 users:update 方法傳送 PUT 要求。

指派資料庫角色時，您可以更新使用者密碼政策參數。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USER_ID：使用者 ID
  • ROLE_1、ROLE_2、...、ROLE_N：要指派給使用者的資料庫角色
在 type 欄位中，指定 BUILT_IN 來代表 Cloud SQL 使用者類型。這個欄位會決定驗證方法。

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "type": "BUILT_IN",
  "databaseRoles": [
   "ROLE_1",
   "ROLE_2"
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "UPDATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

取代現有使用者的資料庫角色

如要取代或移除使用者的資料庫角色，您必須撤銷其所有現有角色，並指定新的資料庫角色 (如有)。

根據預設，建立內建 PostgreSQL 使用者時，系統會自動授予 cloudsqlsuperuser 角色。如果不想讓使用者保留 cloudsqlsuperuser 角色，請撤銷使用者的現有角色。

gcloud

如要替換使用者的資料庫角色，請撤銷使用者的現有角色，並指派新角色。如要取代使用者的資料庫角色，請使用下列 gcloud sql users assign-roles 指令。

gcloud sql users assign-roles USER_NAME \
--type=BUILT_IN \
--instance=INSTANCE_NAME \
--database-roles=ROLE_1,ROLE_2 \
--revoke-existing-roles

更改下列內容：

  • USER_NAME：使用者名稱。
  • HOST：使用者的主機名稱，可以是特定 IP 位址、位址範圍或任何主機 (%)。
  • INSTANCE_NAME：執行個體的名稱。
  • ROLE_1、ROLE_2：要指派給使用者的新資料庫角色。
在 type 欄位中，指定 BUILT_IN 來代表 Cloud SQL 使用者類型。這個欄位會決定驗證方法。

您也可以撤銷使用者的現有角色，不指派任何角色。例如：

gcloud sql users assign-roles USER_NAME \
--type=BUILT_IN \
--instance=INSTANCE_NAME \
--database-roles= \
--revoke-existing-roles

REST v1

如要更新使用者，請使用 users:update 方法傳送 PUT 要求。

替換使用者的資料庫角色時，您可以在同一個 API 要求中更新使用者密碼政策參數。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USER_ID：使用者 ID
  • ROLE_1、ROLE_2...、ROLE_N：要指派給使用者的新資料庫角色。您也可以指定空白清單。

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "type": "BUILT-IN",
  "databaseRoles": [
   "ROLE_1",
   "ROLE_2"
  ],
  "revokeExistingRoles": true
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "UPDATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

如要更新使用者，請使用 users:update 方法傳送 PUT 要求。

替換使用者的資料庫角色時，您可以在同一個 API 要求中更新使用者密碼政策參數。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USER_ID：使用者 ID
  • ROLE_1、ROLE_2、...、ROLE_N：要指派給使用者的一或多個新資料庫角色。您也可以指定空白清單。

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users

JSON 要求主體：

{
  "name": "USER_ID",
  "type": "BUILT-IN",
  "databaseRoles": [
   "ROLE_1",
   "ROLE_2"
  ],
  "revokeExistingRoles": true
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2025-10-20T22:44:16.656Z",
  "startTime": "2025-10-20T22:44:16.686Z",
  "endTime": "2025-10-20T22:44:20.437Z",
  "operationType": "UPDATE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

變更使用者密碼

您可以透過下列任一方式變更使用者密碼。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 找出要更新的使用者，然後按一下「更多動作」圖示 更多動作圖示。。
  5. 選取「變更密碼」。
  6. 指定新密碼。
  7. 按一下「OK」。

gcloud

使用 gcloud sql users set-password 指令變更密碼。

更改下列內容：

  • USER_NAME：使用者名稱。
  • INSTANCE_NAME：執行個體的名稱。
gcloud sql users set-password USER_NAME \
--instance=INSTANCE_NAME \
--prompt-for-password

REST v1

如要變更使用者密碼，請使用 users:update 方法傳送 PUT 要求。

下列要求會更新使用者帳戶 user_name 的密碼。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID
  • user-id：使用者 ID
  • password：：使用者的新密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/users?name=user-id

JSON 要求主體：

{
  "name": "user-id",
  "password": "password"
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "UPDATE_USER",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

REST v1beta4

如要變更使用者密碼，請使用 users:update 方法傳送 PUT 要求。

下列要求會更新使用者帳戶 user_name 的密碼。

使用任何要求資料之前，請先修改下列項目的值：

  • project-id：專案 ID
  • instance-id：所需的執行個體 ID
  • user-id：使用者 ID
  • password：：使用者的新密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/users?name=user-id

JSON 要求主體：

{
  "name": "user-id",
  "password": "password"
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "UPDATE_USER",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

psql 用戶端

在 psql 提示中，執行 ALTER USER 指令。
  1. 解鎖使用者。 
    ALTER USER USER_NAME WITH LOGIN;
  2. 變更密碼，並在系統提示時輸入密碼。 
    ALTER USER USER_NAME WITH PASSWORD PASSWORD;

如果使用者因密碼政策設定而遭到鎖定，請變更密碼來解鎖。確保變更後的密碼符合密碼政策。

移除使用者密碼政策

您可以從具有內建驗證類型的使用者中移除密碼政策。

gcloud

如要移除使用者密碼政策，請使用 gcloud sql users set-password-policy 指令和 --clear-password-policy 參數。

更改下列內容：

  • USER_NAME：使用者名稱
  • INSTANCE_NAME：執行個體的名稱
  • HOST：使用者的主機名稱，可以是特定 IP 位址、位址範圍或任何主機 (%)
gcloud sql users set-password-policy USER_NAME \
--instance=INSTANCE_NAME \
--host=HOST \
--clear-password-policy

REST v1

如要移除使用者密碼政策，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?name=USER_ID

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "data":
  {
    "passwordValidationUserPolicy" : {}
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

REST v1beta4

如要移除使用者密碼政策，請使用 users:update 方法傳送 PUT 要求。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：執行個體 ID
  • USER_ID：使用者 ID
  • PASSWORD：使用者的密碼

HTTP 方法和網址：

PUT https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?name=USER_ID

JSON 要求主體：

{
  "name": "USER_ID",
  "password": "PASSWORD",
  "data":
  {
    "passwordValidationUserPolicy" : {}
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

移除使用者

預設使用者可以移除使用者。

移除使用者前，您必須捨棄該使用者擁有的所有物件，或重新指派擁有權，並撤銷該角色在其他物件上獲得的所有權限。

控制台

  1. 前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

    前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面

  2. 點選執行個體名稱，開啟執行個體的「總覽」頁面。
  3. 在 SQL 導覽選單中選取「使用者」。
  4. 針對要移除的使用者，按一下「更多動作」圖示 更多動作圖示。。
  5. 依序選取「移除」和「移除」。

gcloud

使用 gcloud sql users delete 指令移除使用者。

更改下列內容：

  • USER_NAME：使用者名稱。
  • INSTANCE_NAME：執行個體的名稱。
gcloud sql users delete USER_NAME \
--instance=INSTANCE_NAME

REST v1

下列要求使用 users:delete 方法刪除指定的使用者帳戶。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USERNAME：使用者或服務帳戶的電子郵件地址

HTTP 方法和網址：

DELETE https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "DELETE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

下列要求使用 users:delete 方法刪除指定的使用者帳戶。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：專案 ID
  • INSTANCE_ID：所需的執行個體 ID
  • USERNAME：使用者或服務帳戶的電子郵件地址

HTTP 方法和網址：

DELETE https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID/users?host=&name=USERNAME

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "DONE",
  "user": "user@example.com",
  "insertTime": "2020-02-07T22:38:41.217Z",
  "startTime": "2020-02-07T22:38:41.217Z",
  "endTime": "2020-02-07T22:38:44.801Z",
  "operationType": "DELETE_USER",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

psql 用戶端

  1. 在 psql 提示中刪除使用者：
    DROP ROLE USER_NAME;

    如要進一步瞭解 DROP ROLE 陳述式，請參閱 PostgreSQL 說明文件。

更新使用者屬性

如要更新使用者屬性等資訊，請務必使用 psql 用戶端。詳情請參閱 PostgreSQL 說明文件中的「資料庫角色」。

後續步驟