用途:在编写 PostgreSQL 数据库访问代码、创建 schema 或管理事务时,强制遵循事务安全、类型安全与命名约定,避免数据损坏和运行时错误。
主要能力与规则: 事务管理:启动事务的方法名必须加 TX_ 前缀,且不得接收连接/执行器参数,内部调用 connection.transaction() 或 db.transaction();参与事务的方法不加 TX_ 前缀,必须接收带默认值的执行器参数。单条 INSERT/UPDATE/DELETE、onConflictDoUpdate 等原子操作和 SELECT 不算启动事务。 类型安全:主键默认使用以 UUID 存储的 ULID,防止 ID 枚举并便于按时间排序;纯连接表、小型查找表、纯内部表可用 serial/identity。金额使用 numeric/decimal 精确类型,禁止 float/double。JSONB 列必须标注类型,结构已知用类型化 schema,否则用 Record<string, unknown>。 读写分离:编译期区分读写客户端与只读客户端,查询方法默认只读,仅在需要变更时使用读写客户端。 命名约定:数据库对象统一 snake_case,表如 user_preferences,列如 created_at,索引如 idx_users_email,外键如 fk_orders_users;应用代码映射为惯用大小写。 Schema 模式:所有表含 created_at、updated_at,按需加 deleted_at 软删除、tenant_id 多租户;主动为外键列及 WHERE、JOIN、ORDER BY 涉及的列建索引。 并发:多数操作使用默认 Read Committed;金融、库存/计数等用 Serializable,关键区用 SELECT ... FOR UPDATE 悲观锁。 迁移:始终采用 generate + migrate 流程,先改代码 schema,生成迁移文件,审查 SQL 后再应用,生产环境禁用 auto-push。
适用场景:使用 PostgreSQL 的后端开发,尤其是 TypeScript/Drizzle 项目(具体实现见 typescript-drizzle.md)。
限制:资料未提供安装命令、收费、平台支持等细节;规则为强制约定,违反即应停止并重构。