@google-cloud/cloud-sql-connector

中文文档
1.13.0发布于 2026/11/12Apache-2.0TypeScriptESM + CJS近 30 天下载 2223.9万

一个安全连接到您的 Cloud SQL 实例的 JavaScript 库

中文使用文档
文档目录25 节
  1. 安装
  2. APIs和服务
  3. 全权证书
  4. 使用量
  5. 使用 PostgreSQL
  6. 使用 MySQL
  7. 使用 SQL 服务器
  8. 使用本地代理隧道( Unix 域套接字)
  9. 指定 IP 地址类型
  10. 自动 IAM 数据库认证
  11. 量子后密码学(PQC)
  12. 使用方式 Google Auth Library: Node.js Client 全权证书
  13. 设定定制配额项目
  14. 通过环境变量的额外定制
  15. 使用高级灾后恢复和DNS域名来识别实例
  16. 使用高级回收写出终点 DNS 名称
  17. 配置您的 DNS 记录
  18. 配置连接器
  19. 使用 DNS 域名自动失效
  20. 支助政策
  21. 主要版本生命周期
  22. 支持的节点.js版本
  23. 释放胆量
  24. 捐款
  25. 许可证

cloud-sql-nodejs-connector image

云 SQL 节点.js 连接器

CI npm npm

这个 云 SQL 节点.js 连接器 是 Cloud SQL 连接器, 设计用于 与节点.js运行时间。 使用 Cloud SQL 连接器提供本地 备选案文 云 SQL Auth 代理服务器 提供以下福利:

  • IAM 授权 : 使用 IAM 权限来控制谁可以连接到 您的 Cloud SQL 实例
  • 改进安保: 使用坚固,更新的TLS 1.3加密(包括 自动 混合后量子键交换 openSSL 3.5+运行时间,如节点22.20+和24.5+)和身份 在客户端连接器和服务器端代理机之间进行校验, 独立于数据库协议.
  • 方便时间: 删除使用和分发SSL的要求 证书,以及管理防火墙或源/指定IP地址.
  • (可选) IAM DB 认证 : 向 Cloud SQL 的自动 IAM DB AuthN 特性.

Cloud SQL 节点.js 连接器是一个要和数据库一起使用的软件包 驾驶员。 目前支持的驱动程序有:

安装

您可以使用 npm install数字 :

npm install @google-cloud/cloud-sql-connector

APIs和服务

此库需要以下内容才能成功创建 Cloud SQL 连接 :

全权证书

此库使用 应用程序默认证书( ADC) 战略 解决全权证书问题。 请看 这些如何设置 ADC 的指令 (Google Cloud 应用程序 vs 本地开发, IAM 用户 vs 服务账户证书), 或咨询 节点.js google-auth-library (英语)。 。 。 .

使用量

连接器包意在与数据库驱动程序并用,在 在示例之后, 您可以看到如何创建新连接符并获得有效性 选项,然后可以在启动新连接时使用.

更多例子请检查 examples/ 文件夹.

使用 PostgreSQL

这是怎样开始一个新的 pg 连接池.

import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';
const {Pool} = pg;

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = new Pool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
  max: 5,
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();

使用 MySQL

这是怎样开始一个新的 mysql2 连接池.

import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();

使用 SQL 服务器

这是怎样开始一个新的 tedious 连接.

const {Connection, Request} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

const connector = new Connector();
const clientOpts = await connector.getTediousOptions({
  instanceConnectionName: process.env.SQLSERVER_CONNECTION_NAME,
  ipType: 'PUBLIC',
});
const connection = new Connection({
  // Please note that the `server` property here is not used and is only defined
  // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
  // With that in mind, do not try to change this value since it will have no
  // impact in how the connector works, this README will be updated to remove
  // this property declaration as soon as the tedious driver bug is fixed
  server: '0.0.0.0',
  authentication: {
    type: 'default',
    options: {
      userName: 'my-user',
      password: 'my-password',
    },
  },
  options: {
    ...clientOpts,
    // Please note that the `port` property here is not used and is only defined
    // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this README will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    port: 9999,
    database: 'my-database',
  },
});

connection.connect(err => {
  if (err) {
    throw err;
  }
  let result;
  const req = new Request('SELECT GETUTCDATE()', err => {
    if (err) {
      throw err;
    }
  });
  req.on('error', err => {
    throw err;
  });
  req.on('row', columns => {
    result = columns;
  });
  req.on('requestCompleted', () => {
    console.table(result);
  });
  connection.execSql(req);
});

connection.close();
connector.close();

使用本地代理隧道( Unix 域套接字)

使用 Cloud SQL 节点的另一种可能方法是创建一个 已建立连接的隧道本地代理服务器 使用 Connector.startLocalProxy() 方法代替 Connector.getOptions()。 。 。 .

[注]

这个 startLocalProxy() 目前只支持 MySQL 和 PostgreSQL 的方法 因为它使用目前SQL Server不支持的 Unix 域套接字 .

此替代方法允许使用连接器库 不支持的驱动程序, 如 普里斯马这里有一个 如何使用 PostgreSQL 驱动程序的例子 :

import {Connector} from '@google-cloud/cloud-sql-connector';
import {PrismaClient} from '@prisma/client';

const connector = new Connector();
await connector.startLocalProxy({
  instanceConnectionName: 'my-project:us-east1:my-instance',
  listenOptions: { path: '.s.PGSQL.5432' },
});
const hostPath = process.cwd();

const datasourceUrl =
 `postgresql://my-user:password@localhost/dbName?host=${hostPath}`;
const prisma = new PrismaClient({ datasourceUrl });

connector.close();
await prisma.$disconnect();

关于每个被支持的Cloud SQL数据库中的实例,请参考我们 Prisma 样本。 。 。 .

指定 IP 地址类型

用于节点.js的 Cloud SQL 连接器可用于连接 Cloud SQL 使用公共和私人IP地址以及 私人服务连接 (中文(简体) ). 指定要连接的 IP 地址类型 getOptions 通过 ipType 参数.

默认情况下, 连接将被配置到 'PUBLIC' 连接到 公共IP,用来配置连接,以使用实例的私人IP, 使用情况 'PRIVATE' 页:1 ipType 内容如下:

说明: 如果指定私人IP或私人服务连接, 您的应用程序 必须附在适当的 VPC 网络上才能连接到您的 Cloud SQL 举个例子 对于大多数应用来说,这将需要使用 VPC 连接器。 。 。 .

如何使用私人IP的例子

const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PRIVATE',
});

如何使用 私人服务连接 (PSC) IP 软件

const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PSC',
});

如何使用的实例 IpAddressTypes 类型脚本

import {Connector, IpAddressTypes} from '@google-cloud/cloud-sql-connector';
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: IpAddressTypes.PSC,
});

自动 IAM 数据库认证

使用 自动 IAM 数据库认证 当 使用 Postgres 或 MySQL 驱动程序.

确保 配置您的 Cloud SQL 实例以允许 IAM 认证 财务报告和审定财务报表 添加 IAM 数据库用户。 。 。 .

A 类 Connector 能够配置到 Cloud SQL 实例 自动 IAM 数据库认证 getOptions 通过 authType 参数.

const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});

当为 IAM 认证配置连接时 password 参数 中可以省略 user 参数的格式如下:

Postgres:对于一个IAM用户账户,这是用户的电子邮件地址. 对于一个服务账户,它是服务账户的电子邮件,没有 .gserviceaccount.com 域后缀.

MySQL:对于一个IAM用户账户,这是用户的电子邮件地址,没有 页:1 @ 或域名。 举例来说 [email protected],设置 user 字段改为 test-user。对于服务账户,这是服务 账户的电子邮件地址没有 @project-id.iam.gserviceaccount.com 后缀.

使用 [email protected] 要连接的服务账户见下文.

Postgres 自动 IAM 认证示例

import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';
const {Pool} = pg;

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = new Pool({
  ...clientOpts,
  user: '[email protected]',
  database: 'db-name',
  max: 5,
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();

MySQL 自动 IAM 认证示例

import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'test-sa',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();

如何使用的实例 AuthTypes 类型脚本

对于类型脚本用户 AuthTypes 类型可以直接导入和使用 用于自动IAM数据库认证.

import {AuthTypes, Connector} from '@google-cloud/cloud-sql-connector';
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: AuthTypes.IAM,
});

量子后密码学(PQC)

Cloud SQL 节点连接器在 TLS 1. 3 上建立 mTLS 连接 (单位:千美元)minVersion: 'TLSv1.3')使用Node.js的内置 node:tls 模块 默认曲线偏好。 当运行在包含节点的运行时 OpenSSL 3. 5.0 或以后时间,连接器自动提供和谈判 混合量子后密钥交换组 X25519MLKEM768 (ML-KEM-768) (韩语) 与 X25519 结合,只要Cloud SQL 实例支持它. 无代码 需要更改或连接符选项.

节点和 OpenSSL 运行时间要求

官方节点.js 分布静态捆绑 OpenSSL 而非链接 针对主机操作系统的OpenSSL库. 混合 X25519MLKEM768 键 在正式节点.js放出捆绑的框中支持交换 OpenSSL 3.5+ : (中文(简体) )

  • 节点.js 22 LTS: >= 22.20.0
  • 节点.js 24 LTS: >= 24.5.0
  • 节点.js 25+: 所有释放

如果您使用自定义或 Linux 分发包装的节点.js 二进制 动态链接到系统 OpenSSL, 确保链接到的 OpenSSL 版本 3.5.0 或更新.

您可以检查您的节点所使用 OpenSSL 版本 :

node -p "process.versions.openssl"

产出 3.5.0 或更高(例如, 3.5.8 或者说 3.6.5) 表示 X25519MLKEM768 键交换可用.

向后兼容

混合式后量子键交换是倒相兼容的:

  • 在 OpenSSL 3.5+ 运行时, node:tls 两种混合广告 (单位:千美元)X25519MLKEM768)和古典语(X25519, (中文(简体) ), P-256TLS 中的小组 1.3 国家 ClientHello如果一个 Cloud SQL 实例只提供古典组,则 TLS 握手自动回归古典 X25519 (或 P-256(中文(简体) ) 无出错.
  • 用 OpenSSL 在更古老的节点上运行的应用程序 < 3.5.0 继续使用经典密钥交换在TLS 1.3上连接.

选择退出

禁用客户端的量子后密钥交换( 例如, 在周围工作) 拒绝较大 TLS 1. 3 的遗留网络中间框 ClientHello 页:1 将 TLS 握手限制在经典曲线上, 设置 tls.DEFAULT_ECDH_CURVE 在此之前 打开连接( 注意此更改全过程默认值 node:tls 未指定明示的连接 ecdhCurve:

import tls from 'node:tls';

tls.DEFAULT_ECDH_CURVE = 'X25519:prime256v1:secp384r1';

或者,在不修改应用程序代码的情况下,通过设置 NODE_OPTIONS 环境变量(注: NODE_OPTIONS 也继承了 由子节点js进程进行:

export NODE_OPTIONS='--import=data:text/javascript,import%20tls%20from%20%22node:tls%22%3Btls.DEFAULT_ECDH_CURVE%3D%22X25519:prime256v1:secp384r1%22'

使用方式 Google Auth Library: Node.js Client 全权证书

一个可以用 google-auth-library 全权证书 使用此库时提供 AuthClient 或者说 GoogleAuth 实例 Connector。 。 。 .

npm install google-auth-library
import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector({
  auth: new GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/sqlservice.admin']
  }),
});

在配置不同于 应用程序默认证书 。 见 文档 编辑 google-auth-library 更多信息.

设定定制配额项目

习惯 谷歌 Auth 库 auth 属性也可以用于设置 特定属性,如定制配额项目。 后续行动 前例中, 您可以使用自定义设置配额项目 auth 证书 :

import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector({
  auth: new GoogleAuth({
    clientOptions: {
      quotaProjectId: '<custom quota project>',
    },
  }),
});

通过环境变量的额外定制

通过环境可以改变一些库默认行为 变量。 以下简要提及所支持的价值观及其效果:

  • GOOGLE_APPLICATION_CREDENTIALS: 如果定义了连接符, 将使用此 文件为自定义证书文件,用于认证 Cloud SQL API。 应该 jSON 文件的路径。 你们可以 在此找到更多关于如何获取有效证书文件的文件。 。 。 .
  • GOOGLE_CLOUD_QUOTA_PROJECT:曾为Cloud SQL设置自定义配额项目 API 定义时 .

使用高级灾后恢复和DNS域名来识别实例

连接符可以被配置到使用 DNS 查看实例 . 使用 Cloud SQL 管理的 DNS 名称 高级灾后恢复, (中文(简体) ), 或您管理的域名.

使用高级回收写出终点 DNS 名称

高级灾后恢复 创建您 Cloud SQL 数据库实例的地理分布复制。 表演时 在数据库实例中切换或失效,连接器将优雅地断开 旧的初级法院 与新的初级法院重接.

执行指令 使用写入结束点连接 以获取您初级实例的字端点 DNS 名称。 然后,使用此写出终点 DNS 名称来配置连接符.

配置您的 DNS 记录

连接器可能被配置为使用您定义的 DNS .

在 Cloud SQL 实例中添加 DNS TXT 记录 私营 DNS 服务器 或者您应用程序使用的私人 Google Cloud DNS Zone .

说明: 您强烈反对为您添加 DNS 记录 Cloud SQL 实例到公共 DNS 服务器. 这将允许任何人在 互联网可以发现 Cloud SQL 实例名称 .

例如:假设您想要使用域名 prod-db.mycompany.example.com 连接到您的数据库实例 my-project:region:my-instance。您将创建以下 DNS 记录 :

  • 记录类型 : TXT
  • 名称 : prod-db.mycompany.example.com - 这是应用程序使用的域名
  • 数值 : my-project:region:my-instance - 这是实例名称

配置连接器

配置上述连接器,将连接器ID替换为 dNS名称.

调整以上 MySQL + 数据库/ sql 示例:

import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  domainName: 'prod-db.mycompany.example.com',
  ipType: 'PUBLIC',
});

const pool = await mysql.createPool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();

使用 DNS 域名自动失效

例如:假设应用程序被配置为使用 域名 prod-db.mycompany.example.com最初,私人DNS 带值的区有 TXT 记录 my-project:region:my-instance编辑 应用程序建立连接 my-project:region:my-instance 云SQL实例. 使用 domainName 选项 :

然后重新配置应用程序以使用不同的数据库 实例,更改 prod-db.mycompany.example.com DNS 记录 从 my-project:region:my-instance 改为 my-project:other-region:my-instance-2

应用程序中的连接器检测此更改 DNS记录. 现在,当应用程序使用 域名 prod-db.mycompany.example.com,它将连接到 my-project:other-region:my-instance-2 云SQL实例.

连接器将自动关闭所有已有的连接到 my-project:region:my-instance。这将迫使连接池 建立新的连接。 此外,还可能造成数据库查询正在进行中 失败.

连接器将默认每隔30秒对 DNS 名称的更改进行投票. 您可以使用连接器配置连接频率 failoverPeriod 选项。 当设置为 0 时, 连接器将禁用 民意测验,并只检查DNS记录在创建新时是否有变化 连接.

支助政策

主要版本生命周期

这个项目使用 语义版本,并使用 与支持主要版本有关的生命周期:

活动 - 现行版本获得所有新功能和安全修正(即 否则, 新主要版本为: 保证至少"活动"1年.

折旧 - 贬值的版本继续得到安全和关键 错误修正, 但不接受新特性 。 贬值的版本 支助一年.

不支持 - 任何主要版本 已经贬值了1年 被视为不支持.

支持的节点.js版本

我们的客户端图书馆跟着 节点.js发布时间表。 。 。 . 图书馆兼容所有当前 活动 财务报告和审定财务报表 维修 版本 节点. 如果你在使用"节点"的报废版本,我们建议你 尽快更新到一个积极支持的LTS版本.

Google 的客户端库支持在 a 上的 Node.js runtimes 的遗留版本 以下列警告为依据:

  • 后遗症版本不进行连续整合测试.
  • 一些安全补丁和特性不能被后移植.
  • 依赖关系不能不断更新.

释放胆量

该项目旨在至少每月发布一次。 如果没有新的特性 或已添加修正,具有最新依赖关系的新 PATCH 版本是 释放.

捐款

我们欢迎外部捐助。 请看我们的 贡献指南 关于如何最好地 贡献.

许可证

Apache 版本 2.0

见 自由主义

版本与发布记录

@google-cloud/cloud-sql-connector 共发布 44 个版本,首次发布于 2023/03/15;过去 12 个月发布了 12 个版本。

版本发布日期距今
1.13.0latest2026/11/124 天前
1.12.12026/10/131 个月前
1.12.02026/09/032 个月前
1.11.32026/07/243 个月前
1.11.22026/06/274 个月前
1.11.12026/06/035 个月前

关于 @google-cloud/cloud-sql-connector 的常见问题

@google-cloud/cloud-sql-connector 是什么?

一个安全连接到您的 Cloud SQL 实例的 JavaScript 库

如何安装 @google-cloud/cloud-sql-connector?

在项目目录运行 npm install @google-cloud/cloud-sql-connector,或使用 pnpm add / yarn add / bun add。

@google-cloud/cloud-sql-connector 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@google-cloud/cloud-sql-connector 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@google-cloud/cloud-sql-connector 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@google-cloud/cloud-sql-connector 可以商用吗?

@google-cloud/cloud-sql-connector 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@google-cloud/cloud-sql-connector 的下载量有多少?

根据 npm 官方下载统计,@google-cloud/cloud-sql-connector 在 2026/10/17 – 2026/11/15 这 30 天内被下载 22,238,837 次,日均约 741,295 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@google-cloud/cloud-sql-connector 还在维护吗?

最新版本 1.13.0 发布于 2026/11/12(4 天前);至今共发布 44 个版本,其中过去 12 个月发布了 12 个;首次发布于 2023/03/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。