使用 Cloud SQL 代理连接 MySQL 客户端

本页面介绍了如何使用 Cloud SQL 代理(而不是 IP 地址)将 mysql 客户端连接到 Cloud SQL 实例。

如需了解如何使用 IP 地址将 mysql 客户端连接到 Cloud SQL 实例,请参阅使用 IP 地址连接 mysql 客户端

如需详细了解此代理的工作原理,请参阅关于 Cloud SQL 代理

准备工作

在将 mysql 连接到 Cloud SQL 实例之前,您必须先完成以下操作:

  • 创建一个 Cloud SQL 实例,包括配置默认用户。

    如需详细了解如何创建实例,请参阅创建实例

    如需详细了解如何配置默认用户,请参阅配置默认用户帐号

  • 确定如何连接到您的实例。

    如需了解可以选用的连接方案以及如何选择各方案,请参阅外部应用连接方案

  • 安装了 mysql 客户端

连接 mysql 客户端

使用代理将 mysql 客户端连接到 Cloud SQL 实例包括以下步骤:

  1. 启用 Cloud SQL Admin API
  2. 安装代理
  3. 创建服务帐号
  4. 启动代理
  5. 启动 mysql 会话

1.启用 API

启用 Cloud SQL Admin API。

启用 API

2. 安装代理

Linux 64 位

  1. 下载该代理:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. 使该代理可以执行:
    chmod +x cloud_sql_proxy
    

Linux 32 位

  1. 下载该代理:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. 使该代理可以执行:
    chmod +x cloud_sql_proxy
    

macOS 64 位

  1. 下载该代理:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. 使该代理可以执行:
    chmod +x cloud_sql_proxy
    

macOS 32 位

  1. 下载该代理:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. 使该代理可以执行:
    chmod +x cloud_sql_proxy
    

Windows 64 位

右键点击 https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe,然后选择链接另存为以下载该代理。将文件重命名为 cloud_sql_proxy.exe

Windows 32 位

右键点击 https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe,然后选择链接另存为以下载该代理。将文件重命名为 cloud_sql_proxy.exe
如果此处未包含您的操作系统,您还可以通过源代码编译该代理

3. 创建服务帐号

使用代理建立连接时,代理需要进行 Google Cloud Platform 身份验证。您可以使用 Cloud SDK 凭据,也可以为代理提供指向所创建服务帐号中的本地密钥文件的路径(建议为生产实例采用这种方式)。如果您使用的是 Cloud SDK 凭据,则可跳过此步骤。

如需详细了解服务帐号,请参阅 Google Cloud Platform 身份验证指南

如果使用服务帐号为该代理提供凭据,则您必须在创建该服务帐号时为其分配足够的权限。如果要使用更精细的 Identity Access and Management (IAM) 角色来管理 Cloud SQL 权限,您必须向服务帐号分配一个具有 cloudsql.instances.connect 权限的角色。以下预定义 Cloud SQL 角色拥有这项权限:

  • Cloud SQL Client
  • Cloud SQL Editor
  • Cloud SQL Admin

如果您要使用传统的项目角色(Viewer、Editor、Owner),则该服务帐号必须至少具有 Editor 角色。

  1. 转到 Google Cloud Console 中的服务帐号页面。

    转到“服务帐号”页面

  2. 选择包含您的 Cloud SQL 实例的项目。
  3. 点击创建服务帐号
  4. 创建服务帐号对话框中,为服务帐号提供一个描述性名称。
  5. 角色部分,选择以下角色之一:
    • Cloud SQL > Cloud SQL Client
    • Cloud SQL > Cloud SQL Editor
    • Cloud SQL > Cloud SQL Admin

    或者,您可以通过选择项目 > Editor 使用基本的 Editor 角色,但 Editor 角色拥有整个 Google Cloud 的权限。

    如果您看不到这些角色,则表明您的 Google Cloud 用户可能没有 resourcemanager.projects.setIamPolicy 权限。您可以转到 Google Cloud Console 中的 IAM 页面,然后搜索您的用户 ID 来检查您的权限。

  6. 服务帐号 ID 更改为一个不重复且易于识别的值。
  7. 点击提供新的私钥,并确认密钥类型为 JSON
  8. 点击创建

    私钥文件将下载到您的机器上。您可以将此文件移至其他位置,但要确保密钥文件的安全。

4. 启动代理

根据您的语言和环境,您可以使用 TCP 套接字或 Unix 套接字启动代理。

TCP 套接字

  1. 实例详情页面复制您的实例连接名称。

    例如:myproject:myregion:myinstance

  2. 如果您要使用服务帐号对代理进行身份验证,请记下随服务帐号一起创建的私钥文件在客户端机器上的位置。
  3. 启动代理。

    下面列出了一些可能的代理调用字符串:

    • 使用 Cloud SDK 身份验证:
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306
      
      指定的端口必须尚未被本地数据库服务器等所占用。
    • 使用服务帐号并明确包含实例连接的名称(建议用于生产环境):
      ./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:3306 \
                        -credential_file=<PATH_TO_KEY_FILE> &
      

    如需详细了解代理选项,请参阅用于验证代理身份的选项用于指定实例的选项

Unix 套接字

  1. 如果使用显式实例指定,请从实例详情页面复制您的实例连接名称。
  2. 创建要用来存放代理套接字的目录:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. 如果您要使用服务帐号对代理进行身份验证,请记下随服务帐号一起创建的私钥文件在客户端机器上的位置。
  4. 打开一个新终端窗口并启动代理。

    下面列出了一些可能的代理调用字符串:

    • 使用服务帐号并明确包含实例连接的名称(建议用于生产环境):
      ./cloud_sql_proxy -dir=/cloudsql -instances=<INSTANCE_CONNECTION_NAME> \
                        -credential_file=<PATH_TO_KEY_FILE> &
    • 使用 Cloud SDK 身份验证和自动实例发现:
      ./cloud_sql_proxy -dir=/cloudsql &

    建议最好在单独的终端中启动代理,这样便于您监控其输出,避免与其他程序的输出相混淆。

    如需详细了解代理选项,请参阅用于验证代理身份的选项用于指定实例的选项

  5. 使用 Cloud SQL 代理和 unix 套接字连接到 Cloud SQL 时,请确保套接字文件名的长度不超过系统限制。一般来说,套接字文件名包含 91 到 108 个字符,具体取决于您所用的系统。在 Linux 上,该文件名通常包含 108 个字符;您可以使用以下命令进行检查:
    cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

5. 启动客户端会话

安装并启动代理后,您就可以使用代理启动 mysql 会话。如果您想要使用 mysql 客户端连接到 Cloud SQL 实例,可以使用此命令。

使用的连接字符串取决于您是使用 TCP 套接字还是 UNIX 套接字来启动代理。

TCP 套接字

  1. 启动 mysql 客户端:
    mysql -u <USERNAME> -p --host 127.0.0.1
    

    使用 TCP 套接字建立连接时,可通过 127.0.0.1 访问代理。

  2. 如果出现提示,请输入密码。
  3. 系统会显示 mysql 提示符。

Unix 套接字

  1. 启动 mysql 客户端:
    mysql -u <USERNAME> -p -S /cloudsql/<INSTANCE_CONNECTION_NAME>
    
  2. 输入密码。
  3. 系统会显示 mysql 提示符。

需要帮助?如需获得代理问题排查方面的帮助,请参阅排查 Cloud SQL 代理连接问题。也可参阅我们的 Cloud SQL 支持页面

后续步骤