Azure PostgreSQL TypeScript 连接技能
帮助 Node.js/TypeScript 应用安全连接并高效使用 Azure PostgreSQL。
文档采用参数化查询、SSL校验、Entra ID无密码认证，并建议使用环境变量，未见恶意行为或越权默认操作；但未充分说明数据库写入的确认边界、凭据保密/日志风险、连接字符串中的敏感信息处理、权限最小化和恢复策略，因此扣分。
单连接、连接池、事务和错误处理路径较完整，并说明了关闭连接和超时；但令牌刷新示例的导入不完整（使用了QueryResult和PoolClient却未导入），池刷新存在并发与已借出连接的边界问题，且没有该技能专属测试或静态可验证的异常场景覆盖，因此按静态上限保守评分。
名称、受众、Node.js/TypeScript场景及触发词清晰，覆盖密码、Entra ID、连接池、事务和类型查询；但未明确不适用场景、所需Azure配置前置条件、数据库权限边界或中文使用说明，环境适配证据有限，因此扣分。
文档分层清楚，包含安装、环境变量、认证、核心工作流、错误处理、配置表、最佳实践、MIT许可证、作者和版本号；但缺少变更日志、明确维护责任与更新路径、FAQ/系统化故障排查，且部分示例依赖未声明的上下文，因此扣分。
提供了可直接改造的连接、池化、参数化查询、事务、类型化和令牌刷新示例，核心任务价值明确；但示例含占位符和假定的users/orders表，令牌池示例存在可用性风险，未有该技能关键路径的执行验证，仍需用户审查和修正，因此未接近满分。
技能自身包含具体代码、配置值和参考链接，仓库还提供通用CI与测试材料；但提供的测试并未覆盖该技能关键路径，未见提交的该技能验收测试或第三方执行结果，结论主要依赖静态文本，因此扣分。
- 令牌刷新池示例可能在并发请求或已有借出连接时产生竞态，且示例导入不完整；应在采用前补充编译、并发和令牌过期测试。
- 不要把密码或令牌写入日志；连接字符串示例使用插值，未说明特殊字符转义和秘密管理。
- 写入示例默认执行INSERT，但未定义用户确认、幂等性、最小数据库权限或失败后的业务恢复策略。
它能做什么 & 适用场景
该技能面向使用 Node.js/TypeScript 和 pg（node-postgres）访问 Azure Database for PostgreSQL Flexible Server 的开发者。它提供密码认证和 Microsoft Entra ID 无密码认证示例，并覆盖单客户端、连接池、参数化查询、事务和类型化查询。内容还包括长期运行应用中的 Entra ID 令牌刷新、错误处理、连接字符串和连接池事件。若项目不使用 Azure PostgreSQL、Node.js/TypeScript 或 pg，该技能的适配价值有限。
指导安装 pg、@azure/identity 和 @types/pg；读取 Azure PostgreSQL 主机、数据库、端口及认证相关环境变量；使用 Client 或 Pool 建立带 SSL 的连接；执行参数化 SQL 查询、事务和类型化查询；使用 DefaultAzureCredential 或托管身份获取 PostgreSQL 访问令牌；在令牌过期前重建连接池；处理常见 PostgreSQL 错误代码，并配置连接池大小、超时和生命周期事件。
- 使用 Node.js/TypeScript 构建 Azure PostgreSQL 应用，需要从环境变量创建基础数据库连接。
- 生产服务需要连接池、连接超时、优雅关闭和连接池监控配置。
- 团队希望用参数化查询和事务实现用户、订单等多表操作。
- 应用需要从密码认证迁移到 Microsoft Entra ID 或托管身份认证。
- 长期运行服务需要在 Entra ID 令牌到期前自动刷新数据库连接池。
优缺点一览
- 覆盖密码和 Microsoft Entra ID 两种认证方式。
- 提供生产连接池、事务、参数化查询和优雅关闭模式。
- 包含 TypeScript 查询结果泛型和常见数据库错误代码处理示例。
- 说明 Azure 所需 SSL、令牌范围、端口和连接池配置。
- 范围限定为 Azure Database for PostgreSQL Flexible Server、Node.js/TypeScript 和 pg。
- 不提供数据库迁移、建模、ORM 或表结构设计内容。
- 源码没有明确列出该技能自身的测试场景或运行时兼容性矩阵。
- 连接池和令牌刷新示例需要开发者结合自身生命周期、并发量和 Azure SKU 调整。
如何安装
安装该集合：npx skills add microsoft/skills，在安装向导中选择 azure-postgres-ts。README 说明技能会安装到所选 Agent 的目录，例如 GitHub Copilot 使用 .github/skills/。该技能本身没有单独的安装包或独立安装命令。
如何使用
在支持 Agent Skills 的编码代理中提出包含触发词的请求，例如：“帮我用 TypeScript 和 pg 连接 Azure PostgreSQL，使用连接池和 Microsoft Entra ID 无密码认证。”技能内容会提供安装依赖、环境变量、Client/Pool、事务、参数化查询和令牌刷新示例。具体数据库表结构、部署方式和应用框架未在该技能中规定。
对比同类
认证方式可在密码认证与 Microsoft Entra ID 无密码认证之间选择：密码方式配置简单，但 Entra ID 方式使用 DefaultAzureCredential 或托管身份并以访问令牌作为密码。连接方式可在单个 Client 与 Pool 之间选择；技能将连接池作为生产场景推荐方案。