使用 Cloud SQL Auth 代理连接到 Cloud SQL for PostgreSQL

本页面介绍了如何使用 Cloud SQL Auth 代理从本地测试环境连接到 Cloud SQL。借助 Cloud SQL Auth 代理，您无需授权网络或配置 SSL，即可安全访问 Cloud SQL 实例。通过使用 Cloud SQL Auth 代理，您可以安全地连接到 Cloud SQL 实例。

本页面上的说明仅适用于测试环境，不应该用于生产环境。如需详细了解生产环境所需的配置，请参阅在生产环境中使用 Cloud SQL Auth 代理和使用 Cloud SQL Auth 代理进行连接。

准备工作

  1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

    Go to project selector

  2. Make sure that billing is enabled for your Trusted Cloud project.

  3. 启用必要的 Google Cloud API。

    控制台

    在 Trusted Cloud 控制台中，前往 API 页面。

    转到“API”

    启用 Cloud SQL Admin API。

    gcloud

    点击以下按钮打开 Cloud Shell，以通过命令行直接在浏览器中访问您的 Trusted Cloud 资源。Cloud Shell 可用于运行本快速入门中介绍的 gcloud 命令。

    打开 Cloud Shell

    按照以下方式使用 Cloud Shell 运行 gcloud services enable 命令，以启用本快速入门所需的 API。

    gcloud services enable sqladmin.googleapis.com

    此命令会启用以下 API：

    • Cloud SQL Admin API

  4. Make sure that you have the following role or roles on the project: Cloud SQL Admin (roles/cloudsql.admin), Cloud SQL Viewer (roles/cloudsql.viewer)

    Check for the roles

    1. In the Trusted Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Trusted Cloud console, go to the IAM page.

      前往 IAM
    2. 选择项目。
    3. 点击 授予访问权限。

    4. 在新的主账号字段中，输入您的用户标识符。 这通常是员工身份池中的用户的标识符。如需了解详情，请参阅在 IAM 政策中表示员工池用户，或与您的管理员联系。

    5. 在选择角色列表中，选择一个角色。
    6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
    7. 点击 Save（保存）。

创建 Cloud SQL 实例

在本快速入门中，您将使用 Trusted Cloud 控制台。如需使用 gcloud CLI、cURL 或 PowerShell，请参阅创建实例。

  1. 在 Trusted Cloud 控制台中，前往 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 点击创建实例。
  3. 点击选择 PostgreSQL。
  4. 在实例 ID 字段中，输入 myinstance。
  5. 在密码字段中，输入 postgres 用户的密码。

  6. 点击创建实例。

    您会返回到实例列表。您可以立即点击新实例以查看详细信息，但该实例只能在初始化并启动之后才可用于其他操作。

    ：在此示例中，将使用默认设置（包括公共 IP 地址）创建实例。

Debian/Ubuntu

通过软件包管理系统安装 psql 客户端：

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

通过软件包管理系统安装 psql 客户端：

sudo yum install postgresql

openSUSE

通过软件包管理系统安装 psql 客户端：

sudo zypper install postgresql

其他平台

  1. 从 PostgreSQL 下载页面下载适用于您的平台的 PostgreSQL 核心发行版。
    核心发行版包含 psql 客户端。
  2. 按照下载页面上的说明安装 PostgreSQL 数据库。

安装 Cloud SQL Auth 代理客户端

您下载的 Cloud SQL Auth 代理二进制文件取决于您的操作系统，以及该系统使用的是 32 位还是 64 位内核。大多数较新的硬件使用的是 64 位内核。如果您不确定自己的机器运行的内核是 32 位还是 64 位，请使用 uname -a 命令（Linux 或 macOS）。对于 Windows，请参阅 Windows 文档。

Linux 64 位

  1. 下载 Cloud SQL Auth 代理： 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.linux.amd64
  2. 使 Cloud SQL Auth 代理可执行： 
    chmod +x cloud-sql-proxy

Linux 32 位

  1. 下载 Cloud SQL Auth 代理： 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.linux.386
  2. 如果找不到 curl 命令，请运行 sudo apt install curl 并重复执行下载命令。
  3. 使 Cloud SQL Auth 代理可执行： 
    chmod +x cloud-sql-proxy

macOS 64 位

  1. 下载 Cloud SQL Auth 代理： 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.darwin.amd64
  2. 使 Cloud SQL Auth 代理可执行： 
    chmod +x cloud-sql-proxy

Mac M1

  1. 下载 Cloud SQL Auth 代理： 
      curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.darwin.arm64
  2. 使 Cloud SQL Auth 代理可执行： 
      chmod +x cloud-sql-proxy

Windows 64 位

右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x64.exe，然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud-sql-proxy.exe。

Windows 32 位

右键点击 https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.17.1/cloud-sql-proxy.x86.exe，然后选择链接另存为以下载 Cloud SQL Auth 代理。将文件重命名为 cloud-sql-proxy.exe。

Cloud SQL Auth 代理 Docker 映像

Cloud SQL Auth 代理有不同的容器映像，例如 distroless、alpine 和 buster。默认的 Cloud SQL Auth 代理容器映像使用不包含 shell 的 distroless。如果您需要 shell 或相关工具，请下载基于 alpine 或 buster 的映像。如需了解详情，请参阅 Cloud SQL Auth 代理容器映像。

您可以通过 Docker 使用以下命令将最新映像拉取到本地机器：

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.17.1

其他操作系统

对于此处未列出的其他操作系统，您可以通过源代码编译 Cloud SQL Auth 代理。

获取实例连接名称

  1. 在 Trusted Cloud 控制台中，前往 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 点击实例名称，打开其概览页面。
  3. 在连接到此实例部分，复制连接名称。连接名称的格式为 projectID:region:instanceID。

启动 Cloud SQL Auth 代理

在专有的终端中启动 Cloud SQL Auth 代理，以便监控其输出。将 INSTANCE_CONNECTION_NAME 替换为您在上一步中复制的实例连接名称。

对于 Linux 环境，使用以下命令启动 Cloud SQL Auth 代理：

./cloud-sql-proxy INSTANCE_CONNECTION_NAME

在 Windows 中的 PowerShell 中，使用以下命令启动 Cloud SQL Auth 代理：

.\cloud-sql-proxy.exe INSTANCE_CONNECTION_NAME

系统会显示类似以下内容的消息：

Listening on 127.0.0.1:5432 for INSTANCE_CONNECTION_NAME
Ready for new connections

将 DB_NAME 替换为 Cloud SQL 数据库的名称后，运行以下命令：

psql "host=127.0.0.1 port=5432 sslmode=disable dbname=DB_NAME user=postgres"

在“输入密码：”提示符处，输入您的 PostgreSQL 账号的密码。

验证 PostgreSQL 提示符是否显示。您已使用 psql 客户端连接到数据库。

返回到您启动了 Cloud SQL Auth 代理的终端窗口。您应该会看到如下所示的消息：

New connection for myInstance

清理

为避免因本页中使用的资源导致您的 Trusted Cloud 账号产生费用，请按照以下步骤操作。

  1. 在 Trusted Cloud 控制台中，前往 Cloud SQL 实例页面。

    转到“Cloud SQL 实例”

  2. 选择 myinstance 实例以打开实例详情页面。
  3. 在页面顶部的图标栏中，点击删除。
  4. 在删除实例窗口中，输入实例的名称，然后点击删除。

可选的清理步骤

如果您没有使用在本快速入门中启用的 API，则可以将其停用。

  • 在本快速入门中启用的 API：
    • Cloud SQL Admin API

  1. 在 Trusted Cloud 控制台中，前往 API 页面。

    转到“API”

  2. 选择 Cloud SQL Admin API，然后点击停用 API 按钮。

后续步骤