faasjs-pg

FaasJS PostgreSQL

默认工作流

1. 保持表声明、迁移、查询和测试一致。
2. 优先使用类型化的 QueryBuilder 子句，再使用原始 SQL。
3. 对原始 SQL 中的值使用参数化，并明确界定可信边界。
4. 让迁移保持确定性、可按字典序排序，并尽可能可逆。
5. 如果查询推断属于行为的一部分，请将运行时数据库断言与类型断言配对使用。
6. 如果原子性或行锁很重要，请使用显式事务和并发测试。

加载这些参考资料

• 关于 Tables 上的声明合并和具体行结构：references/guidelines/pg-table-types.md。
• 关于 QueryBuilder、别名、原始 SQL、更新表达式、returning 和边缘语义：references/guidelines/pg-query-builder.md。
• 关于事务模式、事务客户端生命周期、行锁、重试责任归属和并发测试：references/guidelines/pg-transactions-and-locking.md。
• 关于跨 TypeScript 和 API 边界的精确 numeric、decimal 和 bigint 值：references/guidelines/pg-numeric-boundaries.md。
• 关于带时间戳的迁移、SchemaBuilder、TableBuilder 和模式执行：references/guidelines/pg-schema-and-migrations.md。
• 关于 PgVitestPlugin()、共享迁移快照、按文件隔离数据库、DATABASE_URL 和 expectTypeOf(...)：references/guidelines/pg-testing.md。

注意事项

• 将 Tables 声明视为查询推断的真实来源。
• 有意识地使用原始 SQL；将重复的原始 SQL 转为共享辅助函数或构建器子句。
• 写入查询和事务必须受调用方作用域及预期失败处理的保护；切勿让事务客户端逃逸其回调。
• 让 PgVitestPlugin() 负责惰性全局设置：它会迁移一个限定于本次运行的快照，并为每个使用数据库的测试文件提供独立克隆。
• 如果事务还调用 enqueueJob，请加载 FaasJS API And Jobs，并测试业务数据和任务行是否都能回滚。
• 迁移和 PG 集成测试命令需要 DATABASE_URL。

验证

• 如果模式变更需要验证迁移，且 DATABASE_URL 可用，请运行 npx faasjs-pg migrate。
• 使用 vp test <pattern> 运行针对性的 PG 测试。
• 更改对类型敏感的查询行为时，请包含 expectTypeOf(...)。
• 对于锁或并发行为，请使用相互重叠的真实事务；仅断言生成的 SQL 并不足够。