Java通过Cloud Sql Proxy连接GCP上的Postgres SQL

Java通过Cloud SQL Proxy连接GCP Postgres

原创已于 2025-10-05 00:36:02 修改 · 171 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#postgresql

于 2025-02-15 19:32:11 首次发布

要通过 Cloud SQL Proxy 在 Java 应用中连接 Google Cloud Platform (GCP) 上的 PostgreSQL（PG）数据库，你需要按照以下步骤操作：

______

一、前提条件

Google Cloud 项目已创建

已创建 Cloud SQL for PostgreSQL 实例

包括：实例名称、数据库名、用户名、密码

已启用 Cloud SQL Admin API

已设置好 GCP 认证（如使用服务账号）

已安装并配置好 gcloud CLI（可选，但推荐）

Java 开发环境已准备（JDK + Maven/Gradle）

______

二、Cloud SQL Proxy 简介

Cloud SQL Proxy 是一个代理程序，它允许你的应用通过本地安全连接（无需公开 IP）访问 Cloud SQL 实例。它会在你的本地或服务器上启动一个本地端口，该端口会通过加密隧道连接到 GCP 上的 Cloud SQL 实例。

______

三、步骤一：下载并运行 Cloud SQL Proxy

1. 下载 Cloud SQL Proxy

前往 Cloud SQL Proxy 下载页面，选择适合你操作系统的版本（Linux/macOS/Windows），然后下载。

例如，在 Linux 或 macOS 终端中：

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy

chmod +x cloud_sql_proxy

在 Windows 上，可以下载 cloud_sql_proxy.exe。

______

2. 启动 Cloud SQL Proxy

你需要知道以下信息：

INSTANCE_CONNECTION_NAME：格式为 [PROJECT_ID]:[REGION]:[INSTANCE_NAME]

你可以在 GCP Console 的 Cloud SQL 页面中找到该值

本地端口：比如 5432（PostgreSQL 默认端口）

示例（Linux/macOS）：

./cloud_sql_proxy -instances=[PROJECT_ID]:[REGION]:[INSTANCE_NAME]=tcp:5432

将 [PROJECT_ID]:[REGION]:[INSTANCE_NAME] 替换为你的实际值，例如：

./cloud_sql_proxy -instances=my-gcp-project:us-central1:my-postgres-instance=tcp:5432

这将在你的本地 5432 端口上建立一个通往 Cloud SQL 的安全连接。

注意：确保 5432 端口未被占用，或者你可以换成其他端口，如 5433，并在 Java 连接时相应修改端口。

______

四、步骤二：Java 应用连接 PostgreSQL（通过代理）

一旦 Cloud SQL Proxy 正在运行并监听本地端口（如 5432），你的 Java 应用就可以像连接普通 PostgreSQL 数据库一样连接它，只不过主机地址是 localhost 或 127.0.0.1。

1. 添加 JDBC 依赖

如果你使用 Maven，在 pom.xml 中添加 PostgreSQL JDBC 驱动：

<groupId>org.postgresql</groupId>

<artifactId>postgresql</artifactId>

</dependency>

如果使用 Gradle：

implementation 'org.postgresql:postgresql:42.6.0'

______

2. Java 代码示例：连接 Cloud SQL via Proxy

import java.sql.Connection;

import java.sql.DriverManager;

import java.sql.SQLException;

public class CloudSqlProxyExample {

public static void main(String[] args) {

// 数据库连接参数

String jdbcUrl = "jdbc:postgresql://127.0.0.1:5432/your_database_name";

String user = "your_db_user"; // Cloud SQL 中的数据库用户名

String password = "your_db_password"; // Cloud SQL 中的数据库用户密码

try (Connection conn = DriverManager.getConnection(jdbcUrl, user, password)) {

System.out.println("成功连接到 Cloud SQL (通过 Proxy)！");

// 你可以在这里执行 SQL 查询等操作

} catch (SQLException e) {

e.printStackTrace();

System.err.println("连接失败: " + e.getMessage());

}

🔒 注意：

127.0.0.1:5432 是因为 Cloud SQL Proxy 正在本机监听该端口，并转发到 GCP 的 PostgreSQL 实例。

不要使用 Cloud SQL 的公共 IP 或尝试直接连接，除非你明确配置了授权网络和 SSL。

不需要填写 socketFactory 或 cloud-sql-specific JDBC URL 参数，因为你是通过 Proxy 直连，不是使用 Unix Socket 或 Private IP 方式。

______

五、（可选）使用服务账号进行认证（推荐用于生产）

虽然通过 Cloud SQL Proxy 连接时，不需要在代码中处理 GCP 认证（因为代理帮你处理了身份验证和加密通道），但你仍需确保：

你用来运行 Cloud SQL Proxy 的账号（比如你的个人账号或服务账号）有访问该 Cloud SQL 实例的权限。

通常这意味着：

你已通过 gcloud auth login 登录了有权限的账号，或者

你使用了具有 Cloud SQL Client角色的服务账号，并通过环境变量 GOOGLE_APPLICATION_CREDENTIALS 指定了其 JSON 密钥文件。

但请注意：Cloud SQL Proxy 本身并不依赖这个服务账号去连接数据库！它只是建立一条加密通道。真正连接数据库的用户名/密码是你自己数据库的账号！

✅ 总结：Cloud SQL Proxy 负责建立与 GCP 的安全连接，你还是要用数据库的用户名/密码来登录 PostgreSQL。

______

六、其他连接方式对比（供参考）

方式
是否需要公网IP是否需要 Cloud SQL Proxy适用场景通过 Proxy（推荐用于本地/安全连接）
❌ 不需要✅ 需要本地开发、无公网IP、安全隧道通过 Private IP（VPC 内部）
❌ 不需要公网❌ 不需要GCP 内部服务，如 Cloud Run / GKE 在同一个 VPC通过 Public IP + SSL

✅ 需要❌ 不需要直接公网访问（不推荐，除非必要）______

七、总结：Java 通过 Cloud SQL Proxy 连接 GCP PostgreSQL 的关键点

下载并运行 Cloud SQL Proxy，指定你的 Cloud SQL 实例，映射到本地端口（如 5432）。

确保你的 Java 应用连接的是 localhost:5432（或你指定的端口），使用标准 PostgreSQL JDBC 驱动。

连接参数：

JDBC URL：jdbc:postgresql://127.0.0.1:5432/数据库名

用户名/密码：你在 Cloud SQL 中创建的数据库用户凭证

不需要在代码中配置 GCP 认证或 Cloud SQL 特殊参数（如 socketFactory），除非你不用 Proxy 而走其他连接方式。

推荐使用服务账号管理 Cloud SQL 实例权限，但连接数据库本身还是用数据库账号。

______

八、附加：通过命令行测试连接（可选）

在运行 Cloud SQL Proxy 后，你可以使用 psql 命令行工具测试是否能连接：