从本地计算机连接到 Cloud SQL for PostgreSQL

从本地计算机连接到 Cloud SQL for PostgreSQL

MySQL   |  PostgreSQL   |  SQL Server

了解如何使用 Google Cloud 控制台和客户端应用在连接到 PostgreSQL 实例的 Linux、macOS 或 Windows 本地计算机上部署示例应用。

假设您及时完成所有步骤，则本快速入门中所创建资源的费用通常不会超过 1 美元 (USD)。

准备工作

注意：您使用的项目名称必须包含 4 到 30 个字符。当您输入项目名称时，表单会向您推荐一个项目 ID，您可以修改该 ID。项目 ID 必须包含 6 到 30 个字符，且必须以小写字母开头。其余字符可以使用短划线、小写字母或数字，但最后一个字符不能是短划线。

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

6. 启用在本地计算机上运行 Cloud SQL 示例应用所需的 Cloud API。

   控制台

   点击启用 API 按钮以启用本快速入门所需的 API。

   启用 API

   这将启用以下 API：

   • Cloud SQL Admin API
   • IAM API

   gcloud

   安装 gcloud CLI，以通过命令行访问 Google Cloud 资源。gcloud CLI 用于运行本快速入门中提供的 gcloud CLI 命令。所有命令的格式均设置为在 Linux/macOS 终端或 Windows Powershell 中运行。

   打开终端并运行以下 gcloud 命令：

   gcloud services enable sqladmin.googleapis.com iam.googleapis.com

   此命令会启用以下 API：

   • Cloud SQL Admin API
   • IAM API

设置 Cloud SQL

创建 Cloud SQL 实例

控制台

创建具有公共 IP 地址的实例

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

   转到“Cloud SQL 实例”

2. 点击创建实例。
3. 点击选择 PostgreSQL。
4. 在实例 ID 部分输入 quickstart-instance。
5. 为 postgres 用户输入密码。保存此密码以供将来使用。
6. 在选择区域和可用区可用性中点击单个可用区选项。
7. 点击并展开显示配置选项部分。
8. 在机器类型下拉菜单中，选择轻量级。

9. 点击创建实例，然后等待实例初始化并启动。

gcloud

创建具有公共 IP 地址的实例

按照以下方式运行 gcloud sql instances create 命令之前，请将 DB_ROOT_PASSWORD 替换为数据库用户的密码。

（可选）修改以下参数的值：

• --database_version：数据库引擎类型和版本。 如果未指定，则使用 API 默认值。 请参阅 gcloud 数据库版本文档，以查看当前可用版本。
• --cpu：要在机器中设置的核心数。
• --memory：表示要在机器中设置的内存大小的整数。应该提供大小单位（例如 3072MB 或 9GB）。如果未指定单位，则假定为 GB。
• --region：实例的区域位置（例如 asia-east1、us-east1）。如果未指定，则使用默认值 us-central。 请参阅区域的完整列表。

运行 gcloud sql instances create 命令以创建 Cloud SQL 实例。

gcloud sql instances create quickstart-instance --database-version=POSTGRES_13 --cpu=1 --memory=4GB --region=us-central --root-password=DB_ROOT_PASSWORD

创建数据库

控制台

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

   转到“Cloud SQL 实例”

2. 选择 quickstart-instance。
3. 打开数据库标签页。
4. 点击创建数据库。
1. 在新建数据库对话框中，输入 quickstart_db 作为数据库的名称。
   
2. 点击创建。

gcloud

运行 gcloud sql databases create 命令以创建数据库。

gcloud sql databases create quickstart_db --instance=quickstart-instance

创建用户

控制台

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

   转到“Cloud SQL 实例”

2. 如需打开实例的概览页面，请点击实例名称。
3. 从 SQL 导航菜单中选择用户。
4. 点击添加用户账号。
5. 在将一个用户账号添加到实例 instance_nameinstance_name 页面上，添加以下信息：
   • 在用户名字段中，输入 quickstart-user。
   • 在密码字段中，指定数据库用户的密码。记下此密码，以便在本快速入门的后续步骤中使用。
6. 点击添加。

gcloud

替换以下内容：

1. 将 PASSWORD 替换为您的数据库用户密码。记下此密码，以便在本快速入门的后续步骤中使用。

运行 gcloud sql users create 命令以创建用户。

gcloud sql users create quickstart-user --instance=quickstart-instance --password=PASSWORD

Cloud SQL 和本地 PostgreSQL 的用户名长度限制一样。

设置服务账号

创建并配置具有 Cloud SQL Client 角色并有权连接到 Cloud SQL 的 Google Cloud 服务账号。 创建服务账号后，您可能需要等待 60 秒或更长时间才能使用该服务账号。

控制台

创建服务账号

1. 在 Google Cloud 控制台中，转到创建服务账号页面。

打开“创建服务账号”

2. 选择 Google Cloud 项目。
3. 输入 quickstart-service-account 作为服务账号名称。
4. 可选：输入服务账号的说明。
5. 点击创建并继续，然后继续执行下一步。
6. 选择要在项目上授予服务账号的 Cloud SQL Client 角色。
7. 点击继续。
8. 点击完成以完成服务账号的创建。

创建并下载服务账号密钥文件

1. 在 Google Cloud 控制台中，转到服务账号页面。

打开“服务账号”

2. 选择一个项目。
3. 点击要为其创建密钥的 quickstart-service-account 服务账号的电子邮件地址。
4. 点击密钥标签页。
5. 点击添加密钥下拉菜单，然后选择创建新密钥。
6. 选择 JSON 作为密钥类型，然后点击创建。

点击创建即会下载服务账号密钥文件。下载密钥文件后，您无法再次下载。

务必要安全存储密钥文件，因为它能够以服务账号的身份进行身份验证。您可以根据需要移动并重命名此文件。

gcloud

创建服务账号

1. 如需创建服务账号，请运行 gcloud iam service-accounts create 命令：

gcloud iam service-accounts create quickstart-service-account --description="DESCRIPTION" --display-name="quickstart-service-account"

替换以下值：

• DESCRIPTION：服务账号的可选说明
2. 要在项目上向服务账号授予 Cloud SQL Client 角色，请运行 gcloud projects add-iam-policy-binding 命令。将 PROJECT_ID 替换为您的 Google Cloud 项目 ID：

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:quickstart-service-account@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudsql.client"

创建并下载服务账号密钥文件

要使用刚刚从本地计算机创建的服务账号，您需要一个服务账号密钥文件，以服务账号的身份对示例应用进行身份验证。如需创建和下载服务账号密钥文件，请运行 gcloud iam service-accounts keys create 命令：

gcloud iam service-accounts keys create KEY_FILE --iam-account=quickstart-service-account@PROJECT_ID.iam.gserviceaccount.com

替换以下值：

• KEY_FILE：私钥的新输出文件的路径，例如 ~/sa-private-key.json。
• PROJECT_ID：您的 Google Cloud 项目 ID。

现在，服务账号密钥文件已下载到您的本地计算机上。下载密钥文件后，您无法再次下载。

务必要安全存储密钥文件，因为任何人都可以使用它以服务账号的身份进行身份验证。您可以根据需要移动并重命名此文件。

设置编程语言的开发环境

为您的首选编程语言设置本地计算机的开发环境。

Go

完成以下步骤，设置运行 Go 示例应用的开发环境。

1. 转到 Go 开发环境设置指南。
2. 完成安装 Go 部分中的说明。

Java

完成以下步骤，设置运行 Java 示例应用的开发环境。

1. 转到 Java 开发环境设置指南。
2. 完成安装 JDK（Java 开发套件）部分中的说明。
3. 完成安装构建自动化工具中的说明来设置 Apache Maven。

Node.js

完成以下步骤，设置运行 Node.js 示例应用的开发环境。

1. 转到 Node.js 开发环境设置指南。
2. 完成安装 Node.js 和 npm 部分中的说明。

Python

完成以下步骤，设置运行 Python 示例应用的开发环境。

1. 转到 Python 开发环境设置指南。
2. 完成安装 Python 部分中的说明。

安装 Git

安装开源版本控制系统 Git。

Linux

按照官方 Linux 版 Git 安装文档进行操作。

macOS

按照官方 macOS 版 Git 安装文档进行操作。

Windows

按照官方 Windows 版 Git 安装文档进行操作。

克隆示例应用

使用 git clone 命令将示例应用克隆到本地计算机。

Go

运行以下命令，将 Go 示例应用克隆到本地计算机，并将目录更改为包含示例应用的目录。

1. 克隆示例应用。

   git clone https://github.com/GoogleCloudPlatform/golang-samples

2. 将目录更改为包含示例应用的目录。

   cd golang-samples/cloudsql/postgres/database-sql

Java

运行以下命令，将 Java 示例应用克隆到本地计算机，并将目录更改为包含示例应用的目录。

1. 克隆示例应用。

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples

2. 将目录更改为包含示例应用的目录。

   cd java-docs-samples/cloud-sql/postgres/servlet

Node.js

运行以下命令，将 Node.js 示例应用克隆到本地计算机，并将目录更改为包含示例应用的目录。

1. 克隆示例应用。

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

2. 将目录更改为包含示例应用的目录。

   cd nodejs-docs-samples/cloud-sql/postgres/knex

Python

运行以下命令，将 Python 示例应用克隆到本地计算机，并将目录更改为包含示例应用的目录。

1. 克隆示例应用。

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples

2. 将目录更改为包含示例应用的目录。

   cd python-docs-samples/cloud-sql/postgres/sqlalchemy

配置并运行示例应用

配置并运行示例应用。

Linux/macOS

Go

打开终端并运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 /path/to/service/account/key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

export GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILE
export INSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'
export DB_PORT='5432'
export DB_NAME='quickstart_db'
export DB_USER='quickstart-user'
export DB_PASS='YOUR_DB_PASSWORD'

在本地计算机上运行以下命令以获取 Go 示例应用的依赖项并运行示例应用。

1. 获取运行示例应用所需的依赖项。

   go get ./...

2. 运行示例应用。

   go run cmd/app/main.go

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的终端窗口中按 Control+C。

Java

运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 /path/to/service/account/key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

export GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILE
export INSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'
export DB_PORT='5432'
export DB_NAME='quickstart_db'
export DB_USER='quickstart-user'
export DB_PASS='YOUR_DB_PASSWORD'

1. 运行以下命令，获取本地计算机上的 Java 示例应用的依赖项并运行示例应用。

   mvn jetty:run

2. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

3. 要停止示例应用，请在启动示例应用的终端窗口中按 Control+C。

Node.js

1. 运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

   • 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 /path/to/service/account/key.json。
   • 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

   export GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILE
   export INSTANCE_HOST='127.0.0.1'
   export DB_PORT='5432'
   export DB_NAME='quickstart_db'
   export DB_USER='quickstart-user'
   export DB_PASS='YOUR_DB_PASSWORD'

2. 下载 Cloud SQL Auth 代理。

   curl -o cloud-sql-proxy \
   https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.linux.amd64

3. 将 Cloud SQL Auth 代理作为后台进程运行。将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。

   ./cloud-sql-proxy \
   --credentials-file $GOOGLE_APPLICATION_CREDENTIALS \
   INSTANCE_CONNECTION_NAME &

注意：您可以在启动示例应用的终端窗口中使用 fg 命令停止在后台运行 Cloud SQL Auth 代理的进程。这应该会将正在运行的 Cloud SQL Auth 代理作业带到终端前台。然后按 Control+C 停止代理作业。

运行以下命令，将所需的 Node.js 软件包安装到本地计算机上，然后运行示例应用。

1. 安装本地运行应用所需的 Node.js 软件包。

   npm install

2. 运行示例应用。

   npm start

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的终端窗口中按 Control+C。

Python

运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 /path/to/service/account/key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

export GOOGLE_APPLICATION_CREDENTIALS=CREDENTIALS_JSON_FILE
export INSTANCE_CONNECTION_NAME='INSTANCE_CONNECTION_NAME'
export DB_PORT='5432'
export DB_NAME='quickstart_db'
export DB_USER='quickstart-user'
export DB_PASS='YOUR_DB_PASSWORD'

运行以下命令，在本地计算机上设置 Python 示例应用的要求并运行示例应用。

1. 初始化虚拟环境并设置运行示例应用的要求。

   python3 -m venv env
   source env/bin/activate
   pip install -r requirements.txt

2. 运行示例应用。

   python app.py

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的终端窗口中按 Control+C。

Windows

Go

运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 C:\Users\Your-Username\Downloads\key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

$env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"
$env:INSTANCE_CONNECTION_NAME="INSTANCE_CONNECTION_NAME"
$env:DB_PORT="5432"
$env:DB_NAME="quickstart_db"
$env:DB_USER="quickstart-user"
$env:DB_PASS="YOUR_DB_PASSWORD"

在本地计算机上运行以下命令以获取 Go 示例应用的依赖项并运行示例应用。

1. 获取运行示例应用所需的依赖项。

   go get ./...

2. 运行示例应用。

   go run cmd\app\main.go

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的 Powershell 窗口中按 Control+C。

Java

运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 C:\Users\Your-Username\Downloads\key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

$env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"
$env:INSTANCE_CONNECTION_NAME="INSTANCE_CONNECTION_NAME"
$env:DB_PORT="5432"
$env:DB_NAME="quickstart_db"
$env:DB_USER="quickstart-user"
$env:DB_PASS="YOUR_DB_PASSWORD"

1. 运行以下命令，获取本地计算机上的 Java 示例应用的依赖项并运行示例应用。

   mvn jetty:run

2. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

3. 要停止示例应用，请在启动示例应用的 Powershell 窗口中按 Control+C。

Node.js

1. 运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

   • 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 C:\Users\Your-Username\Downloads\key.json。
   • 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

   $env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"
   $env:INSTANCE_HOST="127.0.0.1"
   $env:DB_PORT="5432"
   $env:DB_NAME="quickstart_db"
   $env:DB_USER="quickstart-user"
   $env:DB_PASS="YOUR_DB_PASSWORD"

2. 下载 Cloud SQL Auth 代理。

   wget https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.0.0/cloud-sql-proxy.x64.exe 
   -O cloud-sql-proxy.exe

3. 将 Cloud SQL Auth 代理作为后台进程运行。将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。

   Start-Process -filepath  ".\cloud-sql-proxy.exe" -ArgumentList `
   "--credentials-file $env:GOOGLE_APPLICATION_CREDENTIALS" INSTANCE_CONNECTION_NAME

注意：您可以通过选择由 Start-Process 命令生成的 cmd.exe 窗口来停止在后台运行 Cloud SQL Auth 代理的进程。 关闭该窗口可停止代理作业。

运行以下命令，在本地计算机上安装所需的 Node.js 软件包，然后运行示例应用。

1. 安装本地运行应用所需的 Node.js 软件包。

   npm install

2. 运行示例应用。

   npm start

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的 Powershell 窗口中按 Control+C。

Python

运行以下命令以初始化运行示例应用所需的环境变量。在运行命令之前，请先进行以下替换：

• 将 CREDENTIALS_JSON_FILE 替换为服务账号的 JSON 凭据密钥文件的文件路径，格式为 C:\Users\Your-Username\Downloads\key.json。
• 将 INSTANCE_CONNECTION_NAME 替换为 Cloud SQL 实例概览页面上显示的实例的连接名称。
• 将 YOUR_DB_PASSWORD 替换为您在之前的创建用户快速入门步骤中创建的 quickstart-user 的密码。

$env:GOOGLE_APPLICATION_CREDENTIALS="CREDENTIALS_JSON_FILE"
$env:INSTANCE_CONNECTION_NAME="INSTANCE_CONNECTION_NAME"
$env:DB_PORT="5432"
$env:DB_NAME="quickstart_db"
$env:DB_USER="quickstart-user"
$env:DB_PASS="YOUR_DB_PASSWORD"

运行以下命令，在本地计算机上设置 Python 示例应用的要求并运行示例应用。

1. 初始化虚拟环境并设置运行示例应用的要求。

   virtualenv --python python3 env
   .\env\Scripts\activate
   pip install -r requirements.txt

2. 运行示例应用。

   python app.py

3. 查看正在运行的示例应用。打开浏览器窗口并转到 http://127.0.0.1:8080。

   

4. 要停止示例应用，请在启动示例应用的 Powershell 窗口中按 Control+C。

清理

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

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

   转到“Cloud SQL 实例”

2. 选择 quickstart-instance 实例以打开实例详情页面。
3. 在页面顶部的图标栏中，点击删除。
4. 在删除实例对话框中，输入 quickstart-instance，然后点击删除以删除该实例。

可选的清理步骤

如果您未使用分配给 quickstart-service-account 服务账号的 Cloud SQL client 角色，则可以将其移除。

1. 在 Google Cloud 控制台中，前往 IAM 页面。

   转到 IAM

2. 点击名为 quickstart-service-account 的 IAM 账号的修改图标（形似铅笔）。
3. 删除 Cloud SQL client 角色。
4. 点击保存。

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

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

1. 在 Google Cloud 控制台中，转到 API 页面。

   转到“API”

2. 选择您要停用的任何 API，然后点击停用 API 按钮。

后续步骤

您可以根据自己的需求详细了解如何创建 Cloud SQL 实例。

您还可以了解如何为 Cloud SQL 实例创建 PostgreSQL 用户和数据库。

如需详细了解价格，请参阅 Cloud SQL for PostgreSQL 价格。

详细了解以下内容：

• 使用公共 IP 地址配置 Cloud SQL 实例。
• 使用专用 IP 地址配置 Cloud SQL 实例。

此外，您还可以了解如何从其他 Google Cloud 应用连接到 Cloud SQL 实例：

• 通过在 App Engine 标准环境中运行的应用
• 通过在 Compute Engine 上运行的应用
• 通过在 GKE 上运行的应用
• 通过 Cloud Run 函数
• 通过 Cloud Run