创建实例

本页面介绍如何创建 Cloud SQL for PostgreSQL 实例。

如需详细了解所有实例设置，请参阅实例设置。

新创建的实例具有一个 postgres 数据库。

您在单个项目中可以拥有的实例数上限取决于这些实例的网络架构：

  • 新 SQL 网络架构：每个项目最多可以有 1,000 个实例。
  • 旧 SQL 网络架构：每个项目最多可以有 100 个实例。
  • 同时使用这两种架构：实例数量上限将在 100 到 1,000 之间，具体取决于实例在这两种架构之间的分布情况。

如需请求增加配额，请提交支持请求。读取副本会被计为实例。

准备工作

  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 Google Cloud CLI.

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

    gcloud init

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  8. Install the Google Cloud CLI.

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

    gcloud init
  10. 确保您的用户账号具有 Cloud SQL Admin 和 Compute Viewer 角色。

    转到 IAM 页面

    详细了解角色和权限。

创建 PostgreSQL 实例

控制台

  1. 在 Google Cloud 控制台中，转到 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 点击创建实例。
  3. 在创建实例页面的选择数据库引擎面板上，点击选择 PostgreSQL。

  4. 在创建 SQL Server 实例页面的选择 Cloud SQL 版本部分中，选择实例的 Cloud SQL 版本：Enterprise 或 Enterprise Plus。

    如需详细了解 Cloud SQL 版本，请参阅 Cloud SQL 版本简介。

  5. 选择实例的版本预设值。如需查看可用的预设值，请点击版本预设值菜单。
  6. 在实例信息部分中，选择实例的数据库版本。如需查看可用版本，请点击数据库版本菜单。

    在创建实例后，数据库版本便无法修改。

  7. 在实例信息窗格的实例 ID 字段中，输入您的实例的 ID。

    无需在实例名称中包含项目 ID。此操作将在适当的位置（例如在日志文件中）自动完成。

  8. 为 postgres 用户输入密码。

    9. 如需以明文形式查看密码，请点击显示密码图标。

    您可以手动输入密码，也可以点击生成以让 Cloud SQL 自动为您创建密码。

  9. 可选：按如下方式为实例配置密码政策：
    1. 选中启用密码政策复选框。
    2. 点击设置密码政策按钮，设置以下一个或多个选项，然后点击保存。
      • 最短长度：指定密码必须包含的字符数下限。
      • 密码复杂度：检查密码是否为小写字母、大写字母、数字和非字母数字字符的组合。
      • 限制密码重用：指定不能重复使用的先前密码数量。
      • 禁止使用用户名：禁止在密码中使用用户名。
      • 设置密码更改间隔：指定可以更改密码之前的最短小时数。
  10. 在选择区域和可用区可用性部分，为实例选择区域和可用区。 区域可用性可能因 Cloud SQL for PostgreSQL 版本而异。如需了解详情，请参阅实例设置简介。

    将实例与访问实例的资源置于相同区域内。以后无法更改选择的区域。大多数情况下，您不需要指定可用区。

    如果将实例配置为高可用性示例，则可以同时选择主要可用区和次要可用区。

    在创建实例期间使用次要可用区时，适用以下条件：

    • 主要可用区默认为 Any，次要可用区默认为 Any (different from primary)。
    • 如果同时指定主要可用区和次要可用区，则它们必须是不同的可用区。
  11. 在自定义实例部分，更新实例的设置。首先点击显示配置选项以显示设置组。然后，展开您要查看的群组并自定义设置。所有选定选项的总结会显示在右侧。 自定义这些实例设置是可选操作。系统会为没有进行自定义的所有设置分配默认值。

    下表是实例设置的快速参考。如需详细了解各项设置，请参阅实例设置页面。

    设置 备注
    机器类型
    机器类型 从共享核心或专用核心中进行选择。对于共享核心，每种机器类型都按实例的 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 地址和专用 IP 地址。

    详细了解如何使用公共 IP 地址。
    已获授权的网络

    添加新网络的名称和网络地址。了解详情。
    Google Cloud 服务的专用路径

    选中此复选框即表示您允许其他 Google Cloud 服务（例如 BigQuery）访问 Cloud SQL 中的数据，并通过专用连接对此数据进行查询。
    数据保护
    自动备份 您希望系统开始执行备份的时间范围。 了解详情。
    选择存储备份的位置对于大多数用例，请选择多区域。如果需要将备份存储在特定区域中（例如出于监管原因而需要这样做），请选择“区域”并从“位置”下拉菜单中选择您的区域。
    选择要存储多少个自动备份您想要保留的自动备份数量（1 到 365 天）。了解详情。
    启用时间点恢复 启用时间点恢复和预写式日志记录。了解详情。
    启用删除保护 决定是否保护实例免遭意外删除。了解详情。
    选择要保留多少天的日志 将预写式日志保留时间配置为 1 到 7 天。默认设置为 7 天。了解详情。
    维护
    首选时段 该设置用于确定 Cloud SQL 可对您的实例执行中断性维护的时段（时长为一小时）。如果您没有设置此时段，则系统可能会随时执行中断性维护。了解详情。
    更新顺序 相对于同一项目内的其他实例，此实例的首选更新时间。了解详情。
    标志
    添加标志 您可以使用数据库标志来控制实例的设置和参数。了解详情。
    标签
    添加标签为您添加的每个标签添加键和值。您可以使用标签来帮助组织实例。
    数据缓存
    启用数据缓存（可选） 为 Cloud SQL for PostgreSQL 企业 Plus 版实例启用数据缓存。如需详细了解数据缓存，请参阅数据缓存。
  12. 点击创建实例。

    注意：创建实例可能需要几分钟时间。但是，您可以在创建实例时查看实例的相关信息。

gcloud

如需了解如何安装和开始使用 gcloud CLI，请参阅安装 gcloud CLI。如需了解如何启动 Cloud Shell，请参阅 Cloud Shell 文档。

  1. 使用 gcloud sql instances create 命令创建实例：

    2. 对于 Cloud SQL 企业 Plus 版实例： 
        gcloud sql instances create INSTANCE_NAME \
    --database-version=DATABASE_VERSION \
    --region=REGION \
    --tier=TIER \
    --edition=ENTERPRISE_PLUS

    对于 Cloud SQL 企业版实例：
        gcloud sql instances create INSTANCE_NAME \
    --database-version=DATABASE_VERSION \
    --region=REGION \
    --cpu=NUMBER_CPUS \
    --memory=MEMORY_SIZE \
    --edition=ENTERPRISE
    或者，如果您选择 db-f1-micro 或 db-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)

    例如，以下命令会创建一个具有两个 vCPU 和 7,680 MB 内存的 Cloud SQL 企业版实例：

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

    以下命令会创建一个具有四个核心的 Cloud SQL 企业 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：指定您要用于此实例的 VPC 网络的名称。网络必须已配置专用服务访问通道。仅适用于 Beta 版命令 (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 参数指定要用于创建专用连接的 VPC 网络的名称。
    公共 IP --authorized-networks 只有来自已获授权网络的公共 IP 连接才能连接到您的实例。了解详情。
    强制执行 SSL

    --ssl-mode

    --require-ssl

    ssl-mode 参数会对连接强制执行 SSL/TLS。如需了解详情，请参阅 Cloud SQL for PostgreSQL 的设置。

    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 和由 Cloud SQL 管理并托管在 Google Cloud Certificate Authority Service (CA Service) 上的从属服务器 CA 组成的 CA 层次结构。区域中的从属服务器 CA 会为服务器证书签名，并在该区域中的实例之间共享。

      使用 --server-ca-mode 标志处于预览版阶段。

      此选项目前为预览版。
    • CUSTOMER_MANAGED_CAS_CA：使用此选项，您可以定义 CA 层次结构并管理 CA 证书的变换。您在实例所在的区域的 CA 服务中创建 CA 池。池中的其中一个 CA 用于对服务器证书进行签名。此选项目前为预览版。如需了解详情，请参阅使用客户管理的 CA。
    机器类型和存储空间
    机器类型 --tier 用于指定共享核心实例（db-f1-micro 或 db-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 可对您的实例执行中断性维护的时间范围（时长为一小时）。如果您没有设置此时间范围，则系统可能会随时执行中断性维护。了解详情。
    维护时间 --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 名称（而非 IP 地址）连接到 Cloud SQL 实例，那么请在创建实例时配置自定义主题备用名称 (SAN) 设置。您在自定义 SAN 设置中插入的自定义 DNS 名称会添加到实例的服务器证书的 SAN 字段中。这样，您就可以安全地使用自定义 DNS 名称进行主机名验证。

    您必须先在 DNS 名称与 IP 地址之间设置映射，然后才能在客户端和应用中使用自定义 DNS 名称。这称为 DNS 解析。您可以将最多三个自定义 DNS 名称的英文逗号分隔列表添加到自定义 SAN 设置中。
  2. 请记下系统自动分配的 IP 地址。

    如果您未使用 Cloud SQL Auth 代理，则需要使用此地址作为应用或工具用来连接实例的主机地址。

  3. 为 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 显示“应用完成！”消息。

  3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

删除更改

如需删除更改，请执行以下操作：

  1. 如需停用删除防护，请在 Terraform 配置文件中将 deletion_protection 参数设置为 false。
    deletion_protection =  "false"
  2. 运行以下命令并在提示符处输入 yes，以应用更新后的 Terraform 配置：
    terraform apply

  1. 运行以下命令并在提示符处输入 yes，以移除之前使用 Terraform 配置应用的资源：

    terraform destroy

REST v1

创建实例

本示例创建一个实例。此外，还包括一些可选参数，例如备份和二进制日志记录。如需查看此调用的完整参数列表，请参阅 Instances:insert 页面。如需了解实例设置，包括针对区域的有效值，请参阅实例设置。

请勿在实例 ID 中包含敏感信息或个人身份信息，因为它可供外部用户查看。
无需在实例名称中包含项目 ID。此操作将在适当的位置（例如在日志文件中）自动完成。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID
  • INSTANCE_ID：您的实例 ID
  • REGION：区域
  • DATABASE_VERSION：数据库版本的枚举字符串（例如，POSTGRES_16）
  • PASSWORD：根用户的密码
  • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]

  • EDITION_TYPE：您的 Cloud SQL 版本

  • DATA_CACHE_ENABLED：（可选）设置为 true 可为您的实例启用数据缓存
  • PRIVATE_NETWORK：指定要用于此实例的 Virtual Private Cloud (VPC) 网络的名称。该网络必须已配置专用服务访问通道。
  • AUTHORIZED_NETWORKS：对于公共 IP 连接，请指定可连接到实例的已获授权网络的连接。
  • CA_MODE：为实例指定证书授权机构层次结构（GOOGLE_MANAGED_INTERNAL_CA 或 GOOGLE_MANAGED_CAS_CA）。如果您未指定 serverCaMode，则默认配置为 GOOGLE_MANAGED_INTERNAL_CA。此功能处于预览版阶段。
  • DNS_NAMES：将最多三个 DNS 名称（以英文逗号分隔）添加到 Cloud SQL 实例的服务器证书中。您可以使用单个证书保护多个 DNS 名称。此功能仅在预览版中提供，且仅适用于 CUSTOMER_MANAGED_CAS_CA 实例。

如需在创建实例时设置密码政策，请在请求中添加 passwordValidationPolicy 对象。根据需要设置以下参数：

  • enablePasswordPolicy：设置为 true 时启用密码政策。

    如需移除密码政策，您可以使用 PATCH 请求，并使用 null 作为 enablePasswordPolicy 的值。在这种情况下，其他密码政策参数会重置。

  • minLength：指定密码必须包含的最少字符数。
  • complexity：检查密码是否为小写字母、大写字母、数字和非字母数字字符的组合。默认值为 COMPLEXITY_DEFAULT。
  • reuseInterval：指定不能重复使用的先前密码数量。
  • disallowUsernameSubstring：设置为 true 时，禁止在密码中使用用户名。
  • passwordChangeInterval：指定可以更改密码之前的最短时长。该值以秒为单位，最多包含九个小数位，以 s 结尾。例如 3.5s。

如需创建实例，使其可以与 Vertex AI 集成，请在请求中添加 enableGoogleMlIntegration 对象。借助此集成，您可以将托管在 Vertex AI 中的大语言模型 (LLM) 应用于 Cloud SQL for PostgreSQL 数据库。

根据需要设置以下参数：

  • 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

创建实例

本示例创建一个实例。此外，还包括一些可选参数，例如备份和二进制日志记录。如需查看此调用的完整参数列表，请参阅 instances:insert 页面。如需了解实例设置，包括针对区域的有效值，请参阅实例设置。

请勿在实例 ID 中包含敏感信息或个人身份信息，因为它可供外部用户查看。
无需在实例名称中包含项目 ID。此操作将在适当的位置（例如在日志文件中）自动完成。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的项目 ID
  • INSTANCE_ID：您的实例 ID
  • REGION：区域
  • DATABASE_VERSION：数据库版本的枚举字符串（例如，POSTGRES_16）
  • PASSWORD：根用户的密码
  • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]

  • EDITION_TYPE：您的 Cloud SQL 版本

  • DATA_CACHE_ENABLED：（可选）设置为 true 可为您的实例启用数据缓存
  • PRIVATE_NETWORK：指定要用于此实例的 Virtual Private Cloud (VPC) 网络的名称。该网络必须已配置专用服务访问通道。
  • AUTHORIZED_NETWORKS：对于公共 IP 连接，请指定可连接到实例的已获授权网络的连接。
  • CA_MODE：为实例指定证书授权机构层次结构（GOOGLE_MANAGED_INTERNAL_CA 或 GOOGLE_MANAGED_CAS_CA）。如果您未指定 serverCaMode，则默认配置为 GOOGLE_MANAGED_INTERNAL_CA。 此功能处于预览版阶段。
  • DNS_NAMES：将最多三个 DNS 名称（以英文逗号分隔）添加到 Cloud SQL 实例的服务器证书中。您可以使用单个证书保护多个 DNS 名称。此功能仅在预览版中提供，且仅适用于 CUSTOMER_MANAGED_CAS_CA 实例。

如需在创建实例时设置密码政策，请在请求中添加 passwordValidationPolicy 对象。根据需要设置以下参数：

  • enablePasswordPolicy：设置为 true 时启用密码政策。

    如需移除密码政策，您可以使用 PATCH 请求，并使用 null 作为 enablePasswordPolicy 的值。在这种情况下，其他密码政策参数会重置。

  • minLength：指定密码必须包含的最少字符数。
  • complexity：检查密码是否为小写字母、大写字母、数字和非字母数字字符的组合。默认值为 COMPLEXITY_DEFAULT。
  • reuseInterval：指定不能重复使用的先前密码数量。
  • disallowUsernameSubstring：设置为 true 时，禁止在密码中使用用户名。
  • passwordChangeInterval：指定可以更改密码之前的最短时长。该值以秒为单位，最多包含九个小数位，以 s 结尾。例如 3.5s。

如需创建实例，使其可以与 Vertex AI 集成，请在请求中添加 enableGoogleMlIntegration 对象。借助此集成，您可以将托管在 Vertex AI 中的大语言模型 (LLM) 应用于 Cloud SQL for PostgreSQL 数据库。

根据需要设置以下参数：

  • 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:post 页面上的 API Explorer。

生成写入端点

如果您计划创建 Cloud SQL 企业 Plus 版实例，并且希望 Cloud SQL 自动为该实例生成写入端点，请为您的 Google Cloud 项目启用 Cloud DNS API。

如果您已经有 Cloud SQL 企业 Plus 版实例，并且希望 Cloud SQL 自动生成写入端点，请创建启用了高级灾难恢复的副本。

写入端点是一个全球域名服务 (DNS) 名称，它会自动解析为当前主实例的 IP 地址。如果发生副本故障切换或切换操作，此端点会自动将传入连接重定向到新的主实例。您可以在 SQL 连接字符串中使用写入端点，而不是 IP 地址。通过使用写入端点，您可以避免在发生区域级服务中断时不得不更改应用连接。

如需详细了解如何获取实例的写入端点，请参阅查看实例信息。 如需详细了解如何使用写入端点连接到实例，请参阅使用写入端点进行连接。

自定义实例配置

确定可供 Cloud SQL 实例使用的内存和虚拟核心。 机器类型可用性由您的 Cloud SQL 版本决定。

对于需要实时处理的工作负载（例如在线事务处理 [OLTP]），请确保实例具有足够的内存，能够容纳整个工作集。但是，还存在其他影响内存要求的因素，例如活跃连接数和内部开销进程。您应该执行负载测试，避免在生产环境中出现性能问题。

配置实例时，请选择足够的内存和 vCPU 来处理您的工作负载，并随着工作负载的增加进行升级。机器 vCPU 不足的机器配置可能会导致不再纳入服务等级协议 (SLA) 的覆盖范围。如需了解详情，请参阅运维指南。

Cloud SQL Enterprise Plus 版实例的机器类型

对于 Cloud SQL Enterprise Plus 版本实例，机器类型预定义如下：

企业 Plus 版机器类型 vCPUs 内存 (GB) 本地 SSD
db-perf-optimized-N-2 2 16 375
db-perf-optimized-N-4 4 32 375
db-perf-optimized-N-8 8 64 375
db-perf-optimized-N-16 16 128 750
db-perf-optimized-N-32 32 256 1500
db-perf-optimized-N-48 48 384 3000
db-perf-optimized-N-64 64 512 6000
db-perf-optimized-N-80 80 640 6000
db-perf-optimized-N-96 96 768 6000
db-perf-optimized-N-128 128 864 9000

Cloud SQL Enterprise 版实例的机器类型

对于 Cloud SQL Enterprise 版实例，您还可以使用 gcloud sql instances create 命令来创建自定义实例配置。自定义实例配置允许您选择实例需要的内存大小和 CPU。这种灵活性可让您选择适合您的工作负载的虚拟机类型。

机器类型名称使用以下格式：db-custom-#-#

将第一个 # 占位符替换为机器中的 CPU 数量，将第二个 # 占位符替换为机器中的内存量。

例如，如果您的机器名称为 db-custom，并且您的机器具有 1 个 CPU 和 3840 MB RAM，则机器格式为 db-custom-1-3840。

选择 CPU 数量和内存量时，您选择的配置有一些限制：

  • vCPU 的数量必须为 1 或介于 2 至 96 之间的偶数。
  • 内存必须符合以下条件：
    • 每个 vCPU 的内存量介于 0.9 至 6.5 GB 之间
    • 内存量是 256 MB 的倍数
    • 内存量至少为 3.75 GB (3840 MB)

下表列出了每种旧版机器类型的名称、每种机器类型的 CPU 数和 RAM 以及每种机器类型生成的字符串。

您可以通过在 Google Cloud 控制台中指定等效的 CPU 和 RAM、使用 gcloud CLI 或在 API 中指定 db-custom-#-# 来创建等效的机器类型。

旧版机器类型 vCPUs 内存 (MB) db-custom-CPU-RAM 字符串（API 层字符串）
db-n1-standard-1 1 3840 db-custom-1-3840
db-n1-standard-2 2 7680 db-custom-2-7680
db-n1-standard-4 4 15360 db-custom-4-15360
db-n1-standard-8 8 30720 db-custom-8-30720
db-n1-standard-16 16 61440 db-custom-16-61440
db-n1-standard-32 32 122880 db-custom-32-122880
db-n1-standard-64 64 245760 db-custom-64-245760
db-n1-standard-96 96 368640 db-custom-96-368640
db-n1-highmem-2 2 13312 db-custom-2-13312
db-n1-highmem-4 4 26624 db-custom-4-26624
db-n1-highmem-8 8 53248 db-custom-8-53248
db-n1-highmem-16 16 106496 db-custom-16-106496
db-n1-highmem-32 32 212992 db-custom-32-212992
db-n1-highmem-64 64 425984 db-custom-64-425984
db-n1-highmem-96 96 638976 db-custom-96-638976

限制

  • 您无法使用自定义 SAN 向 Cloud SQL 实例的服务器证书添加超过三个 DNS 名称。
  • 您可以使用自定义 SAN 将 DNS 名称添加到实例的证书中，DNS 名称的长度上限为 253 个字符。
  • 您添加到实例证书中的 DNS 名称不能包含通配符字符 (*) 或尾随点（例如 test.example.com.）。
  • DNS 名称必须有效，如 RFC 1034 中所述。
  • 您只能对 CUSTOMER_MANAGED_CAS_CA 实例使用自定义 SAN。

问题排查

问题 问题排查
错误消息：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 分配范围开始，对于每个条件（额外的实例类型组、额外的区域），将“/子网掩码位数”递减 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 实例。
错误消息：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 向 Cloud SQL 实例的服务器证书添加超过三个 DNS 名称。您最多只能为实例添加 3 个 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. 了解实例设置。