云 SQL 节点.js 连接器
这个 云 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 连接 :
- IAM 主要(用户、服务账户等) 云 SQL 客户端 角色。 。 。 这个IAM本金将用于 全权证书。 。 。 .
- 这个 云 SQL 管理员 API 在您的 Google 云中启用 项目。 默认情况下, API 将被调用到与 学校校长.
全权证书
此库使用 应用程序默认证书( 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
见 自由主义