建立執行個體

本頁面說明如何建立 PostgreSQL 適用的 Cloud SQL 執行個體。

如需所有執行個體設定的詳細資訊,請參閱「執行個體設定」。

新建立的執行個體會包含 postgres 資料庫。

單一專案可擁有的執行個體數量上限取決於這些執行個體的網路架構

  • 全新 SQL 網路架構:每個專案最多可有 1000 個執行個體。
  • 舊版 SQL 網路架構:每個專案最多可有 100 個執行個體。
  • 同時使用兩種架構:視執行個體在兩種架構中的分布情形而定,限制介於 100 到 1000 之間。

如需提高上限,請提交客服案件。唯讀備用資源會計為執行個體。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Install the gcloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command:

    gcloud init
  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Install the gcloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command:

    gcloud init
  12. 請確認使用者帳戶具備 Cloud SQL 管理員和 Compute 檢視者角色。

    前往「IAM」頁面

    進一步瞭解角色和權限。

  13. 建立 PostgreSQL 執行個體。

    控制台

    1. 前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

      前往 Cloud SQL 執行個體

    2. 點選「建立執行個體」
    3. 在「建立執行個體」頁面的「選擇資料庫引擎」面板中,按一下「選擇 PostgreSQL」。
    4. 在「建立 SQL Server 執行個體」頁面的「選擇 Cloud SQL 版本」部分,為執行個體選取 Cloud SQL 版本:EnterpriseEnterprise Plus

      如要進一步瞭解 Cloud SQL 版本,請參閱Cloud SQL 版本簡介

    5. 選取執行個體的版本預設設定。如要查看可用的預設集,請按一下「版本預設集」選單。
    6. 在「執行個體資訊」部分,選取執行個體的資料庫版本。如要查看可用版本,請按一下「資料庫版本」選單。

      執行個體建立完成後,資料庫版本就無法編輯。

    7. 在「Instance info」(執行個體資訊) 窗格的「Instance ID」(執行個體 ID) 欄位中,輸入執行個體的 ID。

      您不需要在執行個體名稱中包含專案 ID,系統會在適當地方 (例如在記錄檔中) 自動加入。

    8. 輸入 postgres 使用者的密碼。
    9. 如要以純文字顯示密碼,請按一下「顯示密碼」圖示。

      您可以手動輸入密碼,也可以按一下「產生」,讓 Cloud SQL 自動建立密碼。

    10. 選用:為執行個體設定密碼政策,步驟如下:
      1. 勾選「啟用密碼政策」核取方塊。
      2. 按一下「設定密碼政策」按鈕,設定下列一或多個選項,然後按一下「儲存」
        • 長度下限:指定密碼的字元數下限。
        • 密碼複雜度:檢查密碼是否混用大小寫、數字和非英數字元。
        • 限制重複使用密碼:指定無法重複使用的舊密碼數量。
        • 禁止使用使用者名稱:禁止在密碼中使用使用者名稱。
        • 設定密碼變更間隔:指定變更密碼前必須經過的最少時數。
    11. 在「Choose region and zonal availability」(選擇區域和可用區供應情形) 專區中,選取執行個體的區域和可用區。視 PostgreSQL 適用的 Cloud SQL 版本而定,可用的區域可能有所不同。詳情請參閱「關於執行個體設定」。

      您的執行個體必須與要存取該執行個體的資源位於相同地區。選取的區域日後無法修改。在大多數情況下,您不需要指定區域。

      如果為執行個體設定高可用性,可以同時選取主要和次要可用區。

      在建立執行個體時使用次要可用區,須符合下列條件:

      • 主要可用區預設為 Any,次要可用區則為 Any (different from primary)
      • 如果同時指定主要和次要可用區,兩者必須是不同的可用區。
    12. 在「自訂執行個體」部分,更新執行個體的設定。 首先,請按一下「顯示設定選項」,顯示設定群組。然後展開要查看及自訂設定的群組。 右側會顯示您所選所有選項的摘要。 您可以選擇是否自訂這些執行個體設定。如果沒有進行任何自訂作業,系統一律會指派預設值。

      下表列出執行個體設定,方便您快速參考。如要進一步瞭解各項設定,請參閱執行個體設定頁面。

      設定 附註
      機器類型
      機型 選取「共用核心」或「專屬核心」。如果是共用核心,每個機器類型會依據執行個體的 CPU (核心) 數量和記憶體大小分類。
      核心 執行個體的 vCPU 數量。 瞭解詳情
      記憶體 執行個體的記憶體量,以 GB 為單位。瞭解詳情
      自訂 如果是專屬核心機型,請選取「自訂」按鈕,建立具有自訂設定的執行個體,而非選取預先定義的設定。選取這個選項時,您需要為執行個體選取核心數量和記憶體大小。瞭解詳情
      儲存空間
      儲存空間類型 判斷執行個體使用的是 SSD 還是 HDD 儲存空間。 瞭解詳情
      儲存空間容量 為執行個體佈建的儲存空間量。 瞭解詳情
      啟用自動增加儲存空間 決定 Cloud SQL 是否要在執行個體可用空間不足時,自動提供更多儲存空間。瞭解詳情
      加密
      Google 管理的加密金鑰預設選項。
      客戶管理的加密金鑰 (CMEK)選取要搭配 Google Cloud Key Management Service 使用的金鑰。瞭解詳情
      連線
      私人 IP 為執行個體新增私人 IP 位址。如要啟用連線至執行個體的功能, 必須進行額外設定。
      您可以選擇指定執行個體用於連線的分配 IP 範圍。
      1. 展開「顯示分配的 IP 範圍選項」
      2. 從下拉式選單中選取 IP 範圍。

      執行個體可以同時擁有公開和私人 IP 位址。

      公開 IP 為執行個體新增公開 IP 位址。然後新增授權網路,連線至執行個體。

      執行個體可以同時擁有公開和私人 IP 位址。

      進一步瞭解如何使用公開 IP

      已授權網路

      新增新網路的名稱和網路位址。 瞭解詳情

      Google Cloud 服務的私人路徑

      選取這個核取方塊後,您允許 BigQuery 等其他 Google Cloud 服務存取 Cloud SQL 中的資料,並透過私人連線查詢這些資料。

      啟用代管連線集區

      勾選這個核取方塊,即可為執行個體啟用代管連線集區。透過「受管理連線集區」,您可以運用集區和多工處理功能,最佳化資源用量和連線延遲,進而擴充 Cloud SQL 執行個體的工作負載。如要進一步瞭解代管連線集區,請參閱代管連線集區總覽

      安全性
      伺服器憑證授權單位模式

      針對這個 Cloud SQL 執行個體,選取簽署伺服器憑證的憑證授權單位 (CA) 類型。瞭解詳情

      根據預設,在 Google Cloud 控制台中建立執行個體時,執行個體會使用Google 管理的內部憑證授權單位 (GOOGLE_MANAGED_INTERNAL_CA),這是每個執行個體的 CA 選項。

      資料保護
      自動備份 您希望備份開始的時間範圍。 瞭解詳情
      選擇要儲存備份的位置多數用途均建議選取「多區域」。如需將備份資料儲存在特定區域 (例如基於法規原因),請選取「區域」,然後從「位置」下拉式選單中選取所需區域。
      選擇要儲存的自動備份量要保留的自動備份數量 (1 到 365 天)。瞭解詳情
      啟用時間點復原 啟用時間點復原和預先寫入記錄。 瞭解詳情
      啟用防刪除功能 決定是否要防止意外刪除執行個體。 瞭解詳情
      啟用刪除執行個體後保留備份功能 決定是否要在刪除執行個體後保留自動和隨選備份。 瞭解詳情
      選擇要保留記錄檔的天數 將預先寫入記錄檔保留期限設為 1 到 7 天。預設為 7 天。 瞭解詳情
      維護
      偏好的維護期間 決定 Cloud SQL 可對執行個體執行中斷型維修的 1 小時期間。如未設定維護期間,系統可能會隨時執行會導致作業中斷的維護作業。瞭解詳情
      更新順序 相較於同專案中的其他執行個體,您偏好的執行個體更新時間。瞭解詳情
      旗標
      新增旗標 您可以使用資料庫標記來控管執行個體的設定和參數。瞭解詳情
      標籤
      新增標籤為新增的每個標籤加入鍵和值。您可以使用標籤整理執行個體。
      資料快取
      啟用資料快取 (選用) 為 PostgreSQL 適用的 Cloud SQL Enterprise Plus 版執行個體啟用資料快取。 如要進一步瞭解資料快取,請參閱資料快取
    13. 按一下「建立執行個體」

      注意:建立執行個體可能需要幾分鐘。不過,您可以在建立執行個體時查看執行個體的相關資訊

    gcloud

    如要瞭解如何安裝及開始使用 gcloud CLI,請參閱安裝 gcloud CLI。如要瞭解如何啟動 Cloud Shell,請參閱 Cloud Shell 說明文件

    1. 使用 gcloud sql instances create 指令建立執行個體:

    2. Cloud SQL Enterprise Plus 版執行個體:
          gcloud sql instances create INSTANCE_NAME \
          --database-version=DATABASE_VERSION \
          --region=REGION \
          --tier=TIER \
          --edition=ENTERPRISE_PLUS
          

      適用於 Cloud SQL Enterprise 版執行個體:
          gcloud sql instances create INSTANCE_NAME \
          --database-version=DATABASE_VERSION \
          --region=REGION \
          --cpu=NUMBER_CPUS \
          --memory=MEMORY_SIZE \
          --edition=ENTERPRISE
          
      或者,如果您選擇 db-f1-microdb-g1-small 做為機器類型,也可以使用 --tier 標記:
          gcloud sql instances create INSTANCE_NAME \
            --tier=API_TIER_STRING \
            --region=REGION
        

      vCPU 數量與記憶體大小的值均受到限制:

      • vCPU 數量必須為 1 或介於 2 到 96 之間的偶數。
      • 記憶體必須:
        • 每個 vCPU 0.9 至 6.5 GB
        • 256 MB 的倍數
        • 至少 3.75 GB (3840 MB)

      舉例來說,下列指令會建立 Cloud SQL Enterprise 版執行個體,其中包含兩個 vCPU 和 7,680 MB 的記憶體:

        gcloud sql instances create myinstance \
        --database-version=POSTGRES_16 \
        --cpu=2 \
        --memory=7680MB \
        --region=us-central1
        

      下列指令會建立具有四個核心的 Cloud SQL Enterprise Plus 版執行個體:

        gcloud sql instances create myinstance \
        --database-version=POSTGRES_16 \
        --tier=db-perf-optimized-N-4 \
        --edition=ENTERPRISE_PLUS \
        --region=us-central1
        
      如要進一步瞭解如何調整 --cpu--memory 的大小,請參閱「自訂執行個體設定」。

      REGION 的預設值為 us-central1

      請勿在執行個體名稱中加入敏感資訊或個人識別資訊,因為外部使用者可以看見此名稱。
      您不需要在執行個體名稱中包含專案 ID,系統會在適當地方 (例如在記錄檔中) 自動加入。

      如要建立高可用性執行個體,可以使用 --zone--secondary-zone 參數指定主要和次要可用區。在建立或編輯執行個體時使用次要區域,須符合下列條件:

      • 可用區必須是有效可用區。
      • 如果指定次要可用區,也必須指定主要可用區。
      • 如果指定主要和次要可用區,兩者必須是不同的可用區。
      • 如果指定主要和次要可用區,兩者必須位於同一區域。

      您可以新增更多參數,決定其他執行個體設定:

      設定 參數 說明
      必要參數
      資料庫版本 --database-version 資料庫版本,取決於 Cloud SQL 版本。
      區域 --region 查看有效值
      設定密碼政策
      啟用密碼政策 --enable-password-policy 啟用後,系統會套用密碼政策。根據預設,密碼政策會停用。使用 --clear-password-policy 參數停用這項政策時,其他密碼政策參數會重設。
      長度下限 --password-policy-min-length 指定密碼的字元數目下限。
      密碼複雜度 --password-policy-complexity 啟用密碼複雜度檢查,確保密碼包含下列各類字元:小寫、大寫、數字和非英數字元。將值設為 COMPLEXITY_DEFAULT
      限制重複使用密碼 --password-policy-reuse-interval 指定無法重複使用的舊密碼數量。
      禁止使用者名稱 --password-policy-disallow-username-substring 禁止在密碼中使用使用者名稱。使用 --no-password-policy-disallow-username-substring 參數即可停用檢查。
      設定密碼變更間隔 --password-policy-password-change-interval 指定變更密碼的最短時間間隔,例如 2m 代表 2 分鐘。
      連線
      私人 IP --network

      --no-assign-ip (選填)

      --allocated-ip-range-name (選填)

      --enable-google-private-path (選填)

      --network:指定您要用於此執行個體的虛擬私人雲端網路名稱。必須已針對網路設定私人服務存取權。僅適用於測試版指令 (gcloud beta sql instances create)。

      --no-assign-ip:執行個體只會有私人 IP 位址。

      --allocated-ip-range-name:如果指定,則設定要分配 IP 範圍的範圍名稱。例如:google-managed-services-default。範圍名稱應符合RFC-1035,且長度介於 1 至 63 個字元之間。(gcloud alpha sql instances create)。

      --enable-google-private-path:如果您使用這個參數,則允許其他 Google Cloud 服務 (例如 BigQuery) 存取 Cloud SQL 中的資料,並透過私人連線對這些資料進行查詢。

      只有在下列情況下,這個參數才有效:

      • 使用 --no-assign-ip 參數。
      • 您可以使用 --network 參數指定要用於建立私人連線的虛擬私有雲網路名稱。

      公開 IP --authorized-networks 如果是公開 IP 連線,只有來自授權網路的連線才能連線至執行個體。瞭解詳情
      強制執行安全資料傳輸層 (SSL)

      --ssl-mode

      --require-ssl

      ssl-mode 參數會強制執行連線的 SSL/TLS 強制執行。詳情請參閱「PostgreSQL 適用的 Cloud SQL 設定」。

      require-ssl 參數會決定是否強制執行透過 IP 的 SSL 連線。require-ssl 是舊版參數。 請改用 ssl-mode。 詳情請參閱 IpConfiguration

      伺服器 CA 模式 --server-ca-mode

      --server-ca-mode 旗標會為執行個體設定伺服器憑證授權單位 (CA) 類型。您可以選取下列任一選項:

      • GOOGLE_MANAGED_INTERNAL_CA:這是預設值。 選用這個選項後,每個 Cloud SQL 執行個體專用的內部 CA,會簽署該執行個體的伺服器憑證。
      • GOOGLE_MANAGED_CAS_CA: 使用這個選項時,系統會採用 CA 階層,其中包含根 CA 和由 Cloud SQL 管理並託管於 Google Cloud 憑證授權單位服務 (CA 服務) 的下層伺服器 CA。 區域中的從屬伺服器 CA 會簽署伺服器憑證,並在區域中的執行個體之間共用。
      • CUSTOMER_MANAGED_CAS_CA: 使用這個選項,您可以定義 CA 層級,並管理 CA 憑證的輪替。在執行個體所在的相同區域中,於 CA 服務中建立 CA 集區。集區中的其中一個 CA 會用於簽署伺服器憑證。 詳情請參閱「使用客戶代管的 CA」。
      機器類型和儲存空間
      機型 --tier 用於指定共用核心執行個體 (db-f1-microdb-g1-small)。如要自訂執行個體設定,請改用 --cpu--memory 參數。請參閱「自訂執行個體設定」。
      儲存空間類型 --storage-type 判斷執行個體使用的是 SSD 還是 HDD 儲存空間。 瞭解詳情
      儲存空間容量 --storage-size 為執行個體佈建的儲存空間量,單位為 GB。 瞭解詳情
      自動增加儲存空間 --storage-auto-increase 決定 Cloud SQL 是否要在執行個體可用空間不足時,自動提供更多儲存空間。瞭解詳情
      自動增加儲存空間上限 --storage-auto-increase-limit 決定 Cloud SQL 自動擴充儲存空間的大小上限。 僅適用於 Beta 版指令 (gcloud beta sql instances create)。 瞭解詳情
      資料快取 (選用) --enable-data-cache 啟用或停用執行個體的資料快取。詳情請參閱資料快取
      自動備份和高可用性
      高可用性 --availability-type 如果為可用性高的執行個體,請設為 REGIONAL瞭解詳情
      次要可用區 --secondary-zone 如要建立高可用性執行個體,可以使用 --zone--secondary-zone parameters 指定主要和次要可用區。在建立或編輯執行個體時使用次要區域,會受到下列限制:
      • 可用區必須是有效可用區。
      • 如果指定次要可用區,也必須指定主要可用區。
      • 如果指定主要和次要可用區,兩者必須是不同的可用區。

        如果指定主要和次要可用區,兩者必須位於同一區域。

      自動備份 --backup-start-time 您希望備份開始的時間範圍。 瞭解詳情
      自動備份的保留設定 --retained-backups-count 要保留的自動備份數量。 瞭解詳情
      二進位檔記錄保留設定 --retained-transaction-log-days 保留預先寫入記錄檔的天數,用於時間點復原。瞭解詳情
      時間點復原 --enable-point-in-time-recovery 啟用時間點復原和預先寫入記錄。 瞭解詳情
      新增資料庫旗標
      資料庫標記 --database-flags 您可以使用資料庫標記來控管執行個體的設定和參數。進一步瞭解資料庫標記
      維護排程
      維護期間 --maintenance-window-day,
      --maintenance-window-hour
      決定 Cloud SQL 可對執行個體執行中斷型維修的 1 小時期間。如未設定維護期間,系統可能會隨時執行會導致作業中斷的維護作業。瞭解詳情
      維護時間 --maintenance-release-channel 相對於同一專案中的其他執行個體,您偏好的執行個體更新時間。使用 preview 查看先前的更新,production 則可查看後續更新。瞭解詳情
      與 Vertex AI 整合
      --enable-google-ml-integration 啟用後,Cloud SQL 執行個體就能連線至 Vertex AI,將即時預測和深入分析要求傳遞給 AI。
      --database-flags cloudsql.enable_google_ml_integration=on 開啟這個旗標後,Cloud SQL 就能與 Vertex AI 整合。
      自訂 SAN
      新增自訂主體別名 (SAN) --custom-subject-alternative-names=DNS_NAMES

      如要使用自訂 DNS 名稱連線至 Cloud SQL 執行個體,而非使用 IP 位址,請在建立執行個體時設定自訂主體別名 (SAN)。您插入自訂 SAN 設定的自訂 DNS 名稱,會新增至執行個體伺服器憑證的 SAN 欄位。這樣一來,您就能安全地使用自訂 DNS 名稱進行主機名稱驗證。

      如要在用戶端和應用程式中使用自訂 DNS 名稱,必須先設定 DNS 名稱與 IP 位址之間的對應關係。這就是所謂的「DNS 解析」。您可以在自訂 SAN 設定中,新增最多三個自訂 DNS 名稱 (以半形逗號分隔)。

    3. 記下系統自動指派的 IP 位址。

      如果您未使用 Cloud SQL Auth Proxy,應用程式或工具會使用這個位址做為連線至執行個體的主機位址。

    4. 設定 postgres 使用者的密碼:
            gcloud sql users set-password postgres \
            --instance=INSTANCE_NAME \
            --password=PASSWORD
            

    Terraform

    如要建立執行個體,請使用 Terraform 資源

    resource "google_sql_database_instance" "postgres_pvp_instance_name" {
      name             = "postgres-pvp-instance-name"
      region           = "asia-northeast1"
      database_version = "POSTGRES_14"
      root_password    = "abcABC123!"
      settings {
        tier = "db-custom-2-7680"
        password_validation_policy {
          min_length                  = 6
          reuse_interval              = 2
          complexity                  = "COMPLEXITY_DEFAULT"
          disallow_username_substring = true
          password_change_interval    = "30s"
          enable_password_policy      = true
        }
      }
      # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
      # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
      deletion_protection = false
    }

    套用變更

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

    準備 Cloud Shell

    1. 啟動 Cloud Shell
    2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

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

      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. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中,前往 UI 中的資源,確認 Terraform 已建立或更新這些資源。

    刪除變更

    如要刪除變更,請按照下列步驟操作:

    1. 如要停用防刪除功能,請在 Terraform 設定檔中將 deletion_protection 引數設為 false
      deletion_protection =  "false"
    2. 執行下列指令,並在提示中輸入 yes,套用更新的 Terraform 設定:
      terraform apply
    1. 執行下列指令,並在提示中輸入 yes,移除先前透過 Terraform 設定套用的資源:

      terraform destroy

    REST v1

    建立執行個體

    這個範例會建立執行個體。其中也包含一些選用參數,例如備份和二進位檔記錄。如需這項呼叫的完整參數清單,請參閱「執行個體:插入」頁面。如要瞭解執行個體設定,包括地區的有效值,請參閱「執行個體設定」。

    請勿在執行個體 ID 中加入敏感資訊或個人識別資訊,因為外部使用者可以看見此 ID。
    您不需要在執行個體名稱中包含專案 ID,系統會在適當地方 (例如在記錄檔中) 自動加入。

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_ID:您的專案 ID
    • INSTANCE_ID:您的執行個體 ID
    • REGION:區域
    • DATABASE_VERSION:資料庫版本的列舉字串 (例如 POSTGRES_17)
    • PASSWORD:根使用者的密碼
    • MACHINE_TYPE:機器 (層級) 類型的列舉字串,如下所示: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE:您的 Cloud SQL 版本

    • DATA_CACHE_ENABLED:(選用) 設為 true 可為執行個體啟用資料快取功能。
    • PRIVATE_NETWORK:指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。必須已針對網路設定私人服務存取權。
    • AUTHORIZED_NETWORKS:如果是公用 IP 連線,請指定可連線至執行個體的授權網路連線。
    • CA_MODE:為執行個體指定憑證授權單位階層,可以是 GOOGLE_MANAGED_INTERNAL_CAGOOGLE_MANAGED_CAS_CA。如未指定 serverCaMode,則預設設定為 GOOGLE_MANAGED_INTERNAL_CA。 這項功能目前為預先發布版
    • DNS_NAMES:在 Cloud SQL 執行個體的伺服器憑證中,以半形逗號分隔,最多新增三個 DNS 名稱。您可以使用單一憑證保護多個 DNS 名稱。這項功能僅適用於預先發布版,且僅適用於 CUSTOMER_MANAGED_CAS_CA 執行個體。

    如要在建立執行個體時設定密碼政策,請在要求中加入 passwordValidationPolicy 物件。視需要設定下列參數:

    • enablePasswordPolicy:設為 true 時,會啟用密碼政策。

      如要移除密碼政策,可以使用 PATCH 要求,並將 enablePasswordPolicy 的值設為 null。在這種情況下,其他密碼政策參數會重設。

    • minLength:指定密碼的字元數下限。
    • complexity:檢查密碼是否混用大小寫、數字和非英數字元。預設值為 COMPLEXITY_DEFAULT
    • reuseInterval:指定不得重複使用的先前密碼數量。
    • disallowUsernameSubstring:設為 true 時,可防止在密碼中使用使用者名稱。
    • passwordChangeInterval:指定變更密碼的最短時間間隔。這個值以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:3.5s

    如要建立可與 Vertex AI 整合的執行個體,請在要求中加入 enableGoogleMlIntegration 物件。整合後,您就能將託管於 Vertex AI 的大型語言模型 (LLM) 套用至 PostgreSQL 適用的 Cloud SQL 資料庫。

    視需要設定下列參數:

    • enableGoogleMlIntegration:將這個參數設為 true 後,Cloud SQL 執行個體就能連線至 Vertex AI,將即時預測和深入分析要求傳遞給 AI
    • cloudsql.enable_google_ml_integration:將這個參數設為 on 時,Cloud SQL 就能與 Vertex AI 整合

    HTTP 方法和網址:

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

    JSON 要求主體:

    {
      "name": "INSTANCE_ID",
      "region": "REGION",
      "databaseVersion": "DATABASE_VERSION",
      "rootPassword": "PASSWORD",
      "settings": {
        "tier": "MACHINE_TYPE",
        "edition": "EDITION_TYPE",
        "enableGoogleMlIntegration": "true" | "false"
        "databaseFlags":
        [
          {
            "name": "cloudsql.enable_google_ml_integration",
            "value": "on" | "off"
          }
        ]
        "dataCacheConfig": {
          "dataCacheEnabled": DATA_CACHE_ENABLED
        },
        "backupConfiguration": {
          "enabled": true
        },
        "passwordValidationPolicy": {
          "enablePasswordPolicy": true
          "minLength": "MIN_LENGTH",
          "complexity": COMPLEXITY_DEFAULT,
          "reuseInterval": "REUSE_INTERVAL",
          "disallowUsernameSubstring": "DISALLOW_USERNAME_SUBSTRING",
          "passwordChangeInterval": "PASSWORD_CHANGE_INTERVAL"
        }
        "ipConfiguration": {
          "privateNetwork": "PRIVATE_NETWORK",
          "authorizedNetworks": [AUTHORIZED_NETWORKS],
          "ipv4Enabled": false,
          "enablePrivatePathForGoogleCloudServices": true,
          "serverCaMode": "CA_MODE",
          "customSubjectAlternativeNames": "DNS_NAMES"
        }
      }
    }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    {
      "kind": "sql#operation",
      "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
      "status": "PENDING",
      "user": "user@example.com",
      "insertTime": "2019-09-25T22:19:33.735Z",
      "operationType": "CREATE",
      "name": "OPERATION_ID",
      "targetId": "INSTANCE_ID",
      "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
      "targetProject": "PROJECT_ID"
    }
    

    回應是長時間執行的作業,可能需要幾分鐘才能完成。

    擷取 IPv4 位址

    擷取新執行個體自動指派的 IPv4 位址:

    使用任何要求資料之前,請先替換以下項目:

    • project-id:您的專案 ID
    • instance-id:在上一個步驟中建立的執行個體 ID

    HTTP 方法和網址:

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

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    {
      "kind": "sql#instance",
      "state": "RUNNABLE",
      "databaseVersion": "MYSQL_8_0_18",
      "settings": {
        "authorizedGaeApplications": [],
        "tier": "db-f1-micro",
        "kind": "sql#settings",
        "pricingPlan": "PER_USE",
        "replicationType": "SYNCHRONOUS",
        "activationPolicy": "ALWAYS",
        "ipConfiguration": {
          "authorizedNetworks": [],
          "ipv4Enabled": true
        },
        "locationPreference": {
          "zone": "us-west1-a",
          "kind": "sql#locationPreference"
        },
        "dataDiskType": "PD_SSD",
        "backupConfiguration": {
          "startTime": "18:00",
          "kind": "sql#backupConfiguration",
          "enabled": true,
          "binaryLogEnabled": true
        },
        "settingsVersion": "1",
        "storageAutoResizeLimit": "0",
        "storageAutoResize": true,
        "dataDiskSizeGb": "10"
      },
      "etag": "--redacted--",
      "ipAddresses": [
        {
          "type": "PRIMARY",
          "ipAddress": "10.0.0.1"
        }
      ],
      "serverCaCert": {
        ...
      },
      "instanceType": "CLOUD_SQL_INSTANCE",
      "project": "project-id",
      "serviceAccountEmailAddress": "redacted@gcp-sa-cloud-sql.iam.gserviceaccount.com",
      "backendType": "SECOND_GEN",
      "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
      "connectionName": "project-id:region:instance-id",
      "name": "instance-id",
      "region": "us-west1",
      "gceZone": "us-west1-a"
    }
    

    在回覆中尋找 ipAddress 欄位。

    REST v1beta4

    建立執行個體

    這個範例會建立執行個體。其中也包含一些選用參數,例如備份和二進位檔記錄。如需此呼叫的完整參數清單,請參閱執行個體:插入頁面。如要瞭解執行個體設定,包括區域的有效值,請參閱執行個體設定

    請勿在執行個體 ID 中加入敏感資訊或個人識別資訊,因為外部使用者可以看見此 ID。
    您不需要在執行個體名稱中包含專案 ID,系統會在適當地方 (例如在記錄檔中) 自動加入。

    使用任何要求資料之前,請先替換以下項目:

    • PROJECT_ID:您的專案 ID
    • INSTANCE_ID:您的執行個體 ID
    • REGION:區域
    • DATABASE_VERSION:資料庫版本的列舉字串 (例如 POSTGRES_17)
    • PASSWORD:根使用者的密碼
    • MACHINE_TYPE:機器 (層級) 類型的列舉字串,如下所示: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE:您的 Cloud SQL 版本

    • DATA_CACHE_ENABLED:(選用) 設為 true,為例項啟用資料快取
    • PRIVATE_NETWORK:指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。必須已針對網路設定私人服務存取權。
    • AUTHORIZED_NETWORKS:如果是公用 IP 連線,請指定可連線至執行個體的授權網路連線。
    • CA_MODE:為執行個體指定憑證授權單位階層,可以是 GOOGLE_MANAGED_INTERNAL_CAGOOGLE_MANAGED_CAS_CA。如未指定 serverCaMode,則預設設定為 GOOGLE_MANAGED_INTERNAL_CA。 這項功能目前為預先發布版
    • DNS_NAMES:在 Cloud SQL 執行個體的伺服器憑證中,以半形逗號分隔,最多新增三個 DNS 名稱。您可以使用單一憑證保護多個 DNS 名稱。這項功能僅適用於預先發布版,且僅適用於 CUSTOMER_MANAGED_CAS_CA 執行個體。

    如要在建立執行個體時設定密碼政策,請在要求中加入 passwordValidationPolicy 物件。 視需要設定下列參數:

    • enablePasswordPolicy:設為 true 時,會啟用密碼政策。

      如要移除密碼政策,可以使用 PATCH 要求,並將 enablePasswordPolicy 的值設為 null。在這種情況下,其他密碼政策參數會重設。

    • minLength:指定密碼的字元數下限。
    • complexity:檢查密碼是否混用大小寫、數字和非英數字元。預設值為 COMPLEXITY_DEFAULT
    • reuseInterval:指定不得重複使用的先前密碼數量。
    • disallowUsernameSubstring:設為 true 時,可防止在密碼中使用使用者名稱。
    • passwordChangeInterval:指定變更密碼的最短時間間隔。這個值以秒為單位,最多可有 9 個小數位數,並應以「s」結尾,例如:3.5s

    如要建立可與 Vertex AI 整合的執行個體,請在要求中加入 enableGoogleMlIntegration 物件。整合後,您就能將託管於 Vertex AI 的大型語言模型 (LLM) 套用至 PostgreSQL 適用的 Cloud SQL 資料庫。

    視需要設定下列參數:

    • enableGoogleMlIntegration:將這個參數設為 true 後,Cloud SQL 執行個體就能連線至 Vertex AI,將即時預測和深入分析要求傳遞給 AI
    • cloudsql.enable_google_ml_integration:將這個參數設為 on 時,Cloud SQL 就能與 Vertex AI 整合

    HTTP 方法和網址:

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

    JSON 要求主體:

    {
      "name": "INSTANCE_ID",
      "region": "REGION",
      "databaseVersion": "DATABASE_VERSION",
      "rootPassword": "PASSWORD",
      "settings": {
        "tier": "MACHINE_TYPE",
        "edition": "EDITION_TYPE",
        "enableGoogleMlIntegration": "true" | "false"
        "databaseFlags":
        [
          {
            "name": "cloudsql.enable_google_ml_integration",
            "value": "on" | "off"
          }
        ]
        "dataCacheConfig": {
          "dataCacheEnabled": DATA_CACHE_ENABLED
        },
        "backupConfiguration": {
          "enabled": true
        },
        "passwordValidationPolicy": {
          "enablePasswordPolicy": true
          "minLength": "MIN_LENGTH",
          "complexity": COMPLEXITY_DEFAULT,
          "reuseInterval": "REUSE_INTERVAL",
          "disallowUsernameSubstring": "DISALLOW_USERNAME_SUBSTRING",
          "passwordChangeInterval": "PASSWORD_CHANGE_INTERVAL"
        }
        "ipConfiguration": {
          "privateNetwork": "PRIVATE_NETWORK",
          "authorizedNetworks": [AUTHORIZED_NETWORKS],
          "ipv4Enabled": false,
          "enablePrivatePathForGoogleCloudServices": true,
          "serverCaMode": "CA_MODE",
          "customSubjectAlternativeNames": "DNS_NAMES"
        }
      }
    }
    

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    {
      "kind": "sql#operation",
      "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
      "status": "PENDING",
      "user": "user@example.com",
      "insertTime": "2020-01-01T19:13:21.834Z",
      "operationType": "CREATE",
      "name": "OPERATION_ID",
      "targetId": "INSTANCE_ID",
      "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
      "targetProject": "PROJECT_ID"
    }
    

    回應是長時間執行的作業,可能需要幾分鐘才能完成。

    擷取 IPv4 位址

    擷取新執行個體自動指派的 IPv4 位址:

    使用任何要求資料之前,請先替換以下項目:

    • project-id:您的專案 ID
    • instance-id:在上一個步驟中建立的執行個體 ID

    HTTP 方法和網址:

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

    如要傳送要求,請展開以下其中一個選項:

    您應該會收到如下的 JSON 回應:

    {
      "kind": "sql#instance",
      "state": "RUNNABLE",
      "databaseVersion": "MYSQL_8_0_18",
      "settings": {
        "authorizedGaeApplications": [],
        "tier": "db-f1-micro",
        "kind": "sql#settings",
        "pricingPlan": "PER_USE",
        "replicationType": "SYNCHRONOUS",
        "activationPolicy": "ALWAYS",
        "ipConfiguration": {
          "authorizedNetworks": [],
          "ipv4Enabled": true
        },
        "locationPreference": {
          "zone": "us-west1-a",
          "kind": "sql#locationPreference"
        },
        "dataDiskType": "PD_SSD",
        "backupConfiguration": {
          "startTime": "18:00",
          "kind": "sql#backupConfiguration",
          "enabled": true,
          "binaryLogEnabled": true
        },
        "settingsVersion": "1",
        "storageAutoResizeLimit": "0",
        "storageAutoResize": true,
        "dataDiskSizeGb": "10"
      },
      "etag": "--redacted--",
      "ipAddresses": [
        {
          "type": "PRIMARY",
          "ipAddress": "10.0.0.1"
        }
      ],
      "serverCaCert": {
        ...
      },
      "instanceType": "CLOUD_SQL_INSTANCE",
      "project": "project-id",
      "serviceAccountEmailAddress": "redacted@gcp-sa-cloud-sql.iam.gserviceaccount.com",
      "backendType": "SECOND_GEN",
      "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
      "connectionName": "project-id:region:instance-id",
      "name": "instance-id",
      "region": "us-west1",
      "gceZone": "us-west1-a"
    }
    

    在回應中尋找 ipAddress 欄位。

    如要瞭解如何建立該工作的基礎 REST API 要求,請參閱 instances:insert 頁面中的 APIs Explorer

    產生寫入端點

    寫入端點是全域網域名稱服務 (DNS) 名稱,會自動解析為目前主要執行個體的 IP 位址。如果發生備用資源容錯移轉或切換作業,這個端點會自動將連入連線重新導向至新的主要執行個體。您可以在 SQL 連線字串中使用寫入端點,取代 IP 位址。使用寫入端點後,發生區域中斷時,您就不必變更應用程式連線。

    如要進一步瞭解如何使用寫入端點連線至執行個體,請參閱使用寫入端點連線至執行個體

    自訂執行個體設定

    決定 Cloud SQL 執行個體可用的記憶體和虛擬核心。機型屬於機器系列,而機器系列的適用性取決於 Cloud SQL 版本。

    對於 Cloud SQL Enterprise Plus 版執行個體,Cloud SQL 會在 N2C4A 機器系列中,為執行個體提供預先定義的機器類型。

    對於 Cloud SQL Enterprise 版執行個體,Cloud SQL 提供預先定義和自訂的機型。

    如果您需要即時處理作業 (例如線上交易處理 (OLTP)),請確保執行個體具備充足的記憶體,可保存整個工作集。不過,其他因素也可能影響記憶體需求,例如有效連線數量和內部額外程序。執行負載測試,避免實際工作環境發生效能問題。

    設定執行個體時,請選取足夠的記憶體和 vCPU 來滿足需求,並隨著需求增加擴充執行個體。如果機器設定的 vCPU 不足,可能無法達到服務水準協議的保證。詳情請參閱操作指南

    如要進一步瞭解 Cloud SQL 執行個體可用的機器類型和機器系列,請參閱機器系列總覽

    疑難排解

    問題 疑難排解
    錯誤訊息:Failed to create subnetwork. Couldn't find free blocks in allocated IP ranges. Please allocate new ranges for this service provider 分配的 IP 範圍內沒有其他可用位址。可能的情況如下:

    • 分配給私人服務連線的 IP 範圍小於 /24。
    • 為私人服務連線分配的 IP 範圍大小,不足以容納 Cloud SQL 執行個體數量。
    • 如果在多個區域中建立執行個體,分配的 IP 範圍大小需求會更大。請參閱已分配範圍大小

    如要解決這個問題,您可以擴展現有的分配 IP 範圍,或為私人服務連線分配額外的 IP 範圍。詳情請參閱分配 IP 位址範圍

    如果您在建立 Cloud SQL 執行個體時使用了 --allocated-ip-range-name 標記,則只能擴充指定的 IP 範圍。

    如要分配新範圍,請注意分配範圍不得與任何現有分配範圍重疊。

    建立新的 IP 範圍後,請執行下列指令更新 VPC 對等互連:

    gcloud services vpc-peerings update \
    --service=servicenetworking.googleapis.com \
    --ranges=OLD_RESERVED_RANGE_NAME,NEW_RESERVED_RANGE_NAME \
    --network=VPC_NETWORK \
    --project=PROJECT_ID \
    --force
        

    如果擴展現有分配範圍,請務必只增加分配範圍,不要縮小。舉例來說,如果原始分配範圍為 10.0.10.0/24,則新的分配範圍至少要為 10.0.10.0/23。

    一般來說,如果從 /24 分配開始,每項條件 (額外執行個體類型群組、額外區域) 將 /mask 遞減 1,是個不錯的經驗法則。舉例來說,如果嘗試在相同配置中建立兩個執行個體類型群組,從 /24 變更為 /23 就足夠。

    擴充現有 IP 範圍後,請使用下列指令更新 VPC 對等互連:

    gcloud services vpc-peerings update \
    --service=servicenetworking.googleapis.com \
    --ranges=RESERVED_RANGE_NAME \
    --network=VPC_NETWORK \
    --project=PROJECT_ID
        
    錯誤訊息:Failed to create subnetwork. Router status is temporarily unavailable. Please try again later. Help Token: [token-ID] 請再次嘗試建立 Cloud SQL 執行個體。
    錯誤訊息:HTTPError 400: Invalid request: Incorrect Service Networking config for instance: PROJECT_ID:INSTANCE_NAME:SERVICE_NETWORKING_NOT_ENABLED.

    使用下列指令啟用 Service Networking API,然後再次嘗試建立 Cloud SQL 執行個體。

    gcloud services enable servicenetworking.googleapis.com \
    --project=PROJECT_ID
        
    錯誤訊息:Failed to create subnetwork. Required 'compute.projects.get' permission for PROJECT_ID 使用私人 IP 位址建立執行個體時,系統會使用 Service Networking API 即時建立服務帳戶。如果您最近才啟用 Service Networking API,系統可能不會建立服務帳戶,導致執行個體建立作業失敗。在這種情況下,您必須等待服務帳戶在整個系統中傳播,或手動新增服務帳戶並授予必要權限。
    錯誤訊息:More than 3 subject alternative names are not allowed. 您嘗試使用自訂 SAN,將超過三個 DNS 名稱新增至 Cloud SQL 執行個體的伺服器憑證。執行個體最多只能新增三個 DNS 名稱。
    錯誤訊息:Subject alternative names %s is too long. The maximum length is 253 characters. 請確認要新增至 Cloud SQL 執行個體伺服器憑證的 DNS 名稱不超過 253 個字元。
    錯誤訊息:Subject alternative name %s is invalid.

    確認要新增至 Cloud SQL 執行個體伺服器憑證的 DNS 名稱符合下列條件:

    • 不含萬用字元。
    • 結尾沒有句點。
    • 符合 RFC 1034 規格。

    後續步驟

    1. 在執行個體上建立 PostgreSQL 資料庫
    2. 在執行個體上建立 PostgreSQL 使用者
    3. 安全地控管執行個體的存取權
    4. 使用 PostgreSQL 用戶端連線至執行個體
    5. 將資料匯入資料庫
    6. 瞭解執行個體設定