# Azure PostgreSQL for TypeScript (node-postgres) 使用支持密码和 Microsoft Entra ID（无密码）身份验证的“pg”（node-postgres）包连接到 Azure Database for PostgreSQL 灵活服务器。 ## 安装 npm install pg @azure/identity npm install -D @types/pg ## 环境变量 # 必填 AZURE_POSTGRESQL_HOST=<服务器>.postgres.database.azure.com AZURE_POSTGRESQL_DATABASE=<数据库> AZURE_POSTGRESQL_PORT=5432 # 用于密码验证 AZURE_POSTGRESQL_USER=<用户名> AZURE_POSTGRESQL_PASSWORD=<密码> # 用于Entra ID认证 AZURE_POSTGRESQL_USER=<用户内部>@<服务器> # 例如，user@contoso.com AZURE_POSTGRESQL_CLIENTID=<托管身份客户端 ID> # 用于用户分配的身份 ## 身份验证 ### 选项 1：密码验证从“pg”导入{客户端，池}；常量客户端 = 新客户端({ 主机：process.env.AZURE_POSTGRESQL_HOST，数据库：process.env.AZURE_POSTGRESQL_DATABASE，用户：process.env.AZURE_POSTGRESQL_USER，密码：process.env.AZURE_POSTGRESQL_PASSWORD，端口：数字（process.env.AZURE_POSTGRESQL_PORT）|| 5432, ssl: {rejectUnauthorized: true } // Azure 必需 }); 等待客户端.connect(); ### 选项 2：Microsoft Entra ID（无密码）- 推荐从“pg”导入{客户端，池}；从“@azure/identity”导入{DefaultAzureCredential}； // 对于系统分配的托管身份 const 凭据 = new DefaultAzureCredential(); // 对于用户分配的托管身份 // const 凭据 = new DefaultAzureCredential({ // ManagedIdentityClientId: process.env.AZURE_POSTGRESQL_CLIENTID // }); // 获取 Azure PostgreSQL 的访问令牌 const tokenResponse = 等待凭证.getToken( “https://ossrdbms-aad.database.windows.net/.default” ）；常量客户端 = 新客户端({ 主机：process.env.AZURE_POSTGRESQL_HOST，数据库：process.env.AZURE_POSTGRESQL_DATABASE， user: process.env.AZURE_POSTGRESQL_USER, // 入口 ID 用户 password: tokenResponse.token, // 令牌作为密码端口：数字（process.env.AZURE_POSTGRESQL_PORT）|| 5432, ssl: { 拒绝未经授权: true } }); 等待客户端.connect(); ## 核心工作流程 ### 1\.单一客户端连接从“pg”导入{客户端}；常量客户端 = 新客户端({ 主机：process.env.AZURE_POSTGRESQL_HOST，数据库：process.env.AZURE_POSTGRESQL_DATABASE，用户：process.env.AZURE_POSTGRESQL_USER，密码：process.env.AZURE_POSTGRESQL_PASSWORD，端口：5432， ssl: { 拒绝未经授权: true } }); 尝试{ 等待客户端.connect(); const result = wait client.query("SELECT NOW() as current_time"); console.log(结果.rows[0].current_time); }最后{ 等待 client.end(); // 始终关闭连接 } ### 2\.连接池（推荐用于生产）从“pg”导入{池}；常量池=新池（{ 主机：process.env.AZURE_POSTGRESQL_HOST，数据库：process.env.AZURE_POSTGRESQL_DATABASE，用户：process.env.AZURE_POSTGRESQL_USER，密码：process.env.AZURE_POSTGRESQL_PASSWORD，端口：5432， ssl: { 拒绝未经授权: true }, // 池配置 max: 20, // 池中的最大连接数 idleTimeoutMillis: 30000, // 30s后关闭空闲连接 connectionTimeoutMillis: 10000 // 新连接超时 }); // 使用池进行查询（自动获取和释放连接） const result = wait pool.query("SELECT * FROM users WHERE id = $1", [userId]); // 多个查询的显式结帐 const client = wait pool.connect(); 尝试{ const res1 = wait client.query("SELECT * FROM users"); const res2 = wait client.query("SELECT * FROM 订单"); }最后{ 客户端.release(); // 将连接返回到池中 } // 关闭时清理等待池.end(); ### 3\.参数化查询（防止 SQL 注入） // 始终使用参数化查询 - 从不连接用户输入常量用户ID = 123; const email =“user@example.com”； // 单个参数 const 结果 = 等待池.query( “从用户中选择 *，其中 id = $1”， [用户 ID] ）； // 多个参数 const 结果 = 等待池.query( “插入用户（电子邮件、姓名、创建时间）值（$1、$2、NOW()）返回*”， [电子邮件，“约翰·多伊”] ）； // 数组参数常量 ID = [1, 2, 3, 4, 5]; const 结果 = 等待池.query( "从用户中选择 * WHERE id = ANY($1::int[])", [ID] ）； ### 4\.交易 const client = wait pool.connect(); 尝试{ 等待客户端.query(“开始”); const userResult = 等待 client.query( “插入用户（电子邮件）值（$1）返回 ID”， [“用户@example.com”] ）； const userId = userResult.rows[0].id; 等待客户端.查询（ “插入订单（user_id，总计）值（$1，$2）”， [用户ID，99.99] ）；等待 client.query("COMMIT"); } 捕获（错误）{ 等待 client.query("ROLLBACK"); 抛出错误； }最后{ 客户端.release(); } ### 5\.交易辅助功能异步函数 withTransaction( 泳池：泳池， fn: (客户端: PoolClient) => Promise ): 承诺 { const client = wait pool.connect(); 尝试{ 等待客户端.query(“开始”); const 结果 = 等待 fn(客户端); 等待 client.query("COMMIT"); 返回结果； } 捕获（错误）{ 等待 client.query("ROLLBACK"); 抛出错误； }最后{ 客户端.release(); } } // 用法 const order =等待withTransaction（池，异步（客户端）=> { const 用户 = 等待 client.query( “插入用户（电子邮件）值（1 美元）返回 *”， [“用户@example.com”] ）； const order = 等待 client.query( “插入订单（user_id，总计）值（$1，$2）返回*”， [用户.行[0].id, 99.99] ）；返回 order.rows[0]; }); ### 6\.使用 TypeScript 进行类型化查询从“pg”导入{池，查询结果}；界面用户{ id：号码；电子邮件：字符串；名称：字符串；创建时间：日期； } // 输入查询结果 const 结果： QueryResult = wait pool.query( “从用户中选择 *，其中 id = $1”， [用户 ID] ）；常量用户：用户|未定义=结果.rows[0]; // 类型安全插入异步函数createUser( 泳池：泳池，电子邮件：字符串，名称：字符串 ): 承诺<用户> { const 结果=等待池.query<用户>( “插入用户（电子邮件、姓名）值（$1、$2）返回*”， [电子邮件、姓名] ）；返回结果.rows[0]; } ## 带有 Entra ID 令牌刷新的池对于长时间运行的应用程序，令牌会过期并需要刷新：从“pg”导入{Pool，PoolConfig}；从“@azure/identity”导入{DefaultAzureCredential，AccessToken}；类 AzurePostgresPool { 私人泳池：泳池 |空=空；私有凭证：DefaultAzureCredential；私人令牌到期：日期|空=空；私有配置：省略; 构造函数（配置：省略）{ this.credential = new DefaultAzureCredential(); this.config = 配置； } 私有异步 getToken(): Promise { const tokenResponse = 等待 this.credential.getToken( “https://ossrdbms-aad.database.windows.net/.default” ）； this.tokenExpiry = new Date(tokenResponse.expiresOnTimestamp); 返回tokenResponse.token； } 私有 isTokenExpired(): 布尔值 { if (!this.tokenExpiry) 返回 true; // 过期前5分钟刷新返回 new Date() >= new Date(this.tokenExpiry.getTime() - 5 * 60 * 1000); } 异步 getPool(): Promise { if (this.pool && !this.isTokenExpired()) { 返回这个.pool； } // 如果令牌过期，则关闭现有池 if (this.pool) { 等待 this.pool.end(); } const token = 等待 this.getToken(); this.pool = 新池({ ...这个.config，密码：令牌 }); 返回这个.pool； } 异步查询 (text: string, params?: any[]): Promise> { const pool = wait this.getPool(); return pool.query(text, params); } 异步结束(): Promise { if (this.pool) { 等待 this.pool.end(); this.pool = null; } } } // 用法 const azurePool = new AzurePostgresPool({ 主机：process.env.AZURE_POSTGRESQL_HOST！，数据库：process.env.AZURE_POSTGRESQL_DATABASE！，用户：process.env.AZURE_POSTGRESQL_USER！，端口：5432， ssl: { 拒绝未经授权: true }, 最多：20 }); const 结果 = 等待 azurePool.query("SELECT NOW()"); ## 错误处理从“pg”导入{DatabaseError}；尝试{ wait pool.query("插入用户（电子邮件）值（$1）", [电子邮件]); } 捕获（错误）{ if (数据库错误的错误实例) { 开关（错误代码）{ 案例“23505”：//unique_violation console.error("重复条目：", error.detail); 休息; 案例“23503”：//foreign_key_violation console.error("外键约束失败:", error.detail); 休息; 案例“42P01”：//未定义的表 console.error("表不存在：", error.message); 休息; case "28P01": // 无效密码 console.error("验证失败"); 休息; case "57P03": //cannot_connect_now（服务器启动） console.error("服务器不可用，请稍后重试"); 休息; 默认： console.error(`PostgreSQL 错误 ${error.code}: ${error.message}`); } } 抛出错误； } ## 连接字符串格式 // 替代方案：使用连接字符串常量池=新池（{ 连接字符串：`postgres://${用户}:${密码}@${主机}:${端口}/${数据库}?sslmode=require` }); // 需要 SSL (Azure) const 连接字符串 = `postgres://user:password@server.postgres.database.azure.com:5432/mydb?sslmode=require`; ## 泳池活动 const pool = new Pool({ /* 配置 */ }); pool.on("连接", (客户端) => { console.log("新客户端连接到池"); }); pool.on("获取", (客户端) => { console.log("客户端从池中签出"); }); pool.on("release", (err, client) => { console.log("客户端返回池"); }); pool.on("删除", (客户端) => { console.log("客户端已从池中删除"); }); pool.on("错误", (err, 客户端) => { console.error("意外的池错误：", err); }); ## Azure 特定配置设置|价值|描述 ---|---|--- `ssl.rejectUnauthorized` | `真实` |始终对 Azure 使用 SSL 默认端口 | `5432` |标准 PostgreSQL 端口 PgBouncer 端口 | `6432` |当 PgBouncer 启用时使用代币范围 | `https://ossrdbms-aad.database.windows.net/.default` | Entra ID 令牌范围令牌生命周期 |约 1 小时 |过期前刷新 ## 池大小指南工作量| `最大` | `idleTimeoutMillis` ---|---|--- 光（开发/测试）| 5-10 | 30000 中等（生产）| 20-30 | 20-30 30000 重度（高并发）| 50-100 | 10000 > **注意**：Azure PostgreSQL 具有基于 SKU 的连接限制。检查您所在层的最大连接数。 ## 最佳实践 1. **始终对生产应用程序使用连接池** 2. **使用参数化查询** \- 切勿连接用户输入 3. **始终关闭连接** \- 使用 `try/finally` 或连接池 4. **启用 SSL** \- Azure 所需（`ssl: {rejectUnauthorized: true }`） 5. **处理令牌刷新** \- Entra ID 令牌在约 1 小时后过期 6. **设置连接超时** \- 避免因网络问题而挂起 7. **使用事务** \- 用于多语句操作 8. **监控池指标** \- 跟踪 `pool.totalCount`、`pool.idleCount`、`pool.waitingCount` 9. **正常关闭** \- 在应用程序终止时调用 `pool.end()` 10. **使用 TypeScript 泛型** \- 为了安全起见，输入您的查询结果 ## 关键类型导入{ 客户，泳池、池客户端，池配置，查询结果，查询结果行，数据库错误，查询配置 } 来自“pg”； ## 参考链接资源 |网址 ---|--- 节点-postgres 文档 | npm 包 | GitHub 存储库 | Azure PostgreSQL 文档 | 无密码连接 | ## 何时使用此技能适用于执行概述中描述的工作流程或操作。

Azure Postgres Ts

包含技能