_contributing

# Postgres 规则编写指南 本文档提供了创建有效的 Postgres 最佳实践规则的指南，这些规则适用于智能体和 LLM。 ## 关键原则 ### 1. 具体的转换模式 展示确切的 SQL 重写。避免哲学性的建议。 **好：** “使用 `WHERE id = ANY(ARRAY[...])` 代替 `WHERE id IN (SELECT ...)`” **坏：** “设计良好的模式” ### 2. 错误优先结构 始终先展示有问题模式，然后展示解决方案。这能训练智能体识别反模式。 markdown **不正确（顺序查询）：** [错误示例] **正确（批量查询）：** [正确示例] ### 3. 量化影响 包含具体指标。帮助智能体优先处理修复。 **好：** “查询速度提升 10 倍”、“索引缩小 50%”、“消除 N+1 问题” **坏：** “更快”、“更好”、“更高效” ### 4. 自包含示例 示例应该是完整且可运行的（或接近可运行）。如果需要上下文，请包含 `CREATE TABLE`。 sql -- 需要时包含表定义以保持清晰 CREATE TABLE users ( id bigint PRIMARY KEY, email text NOT NULL, deleted_at timestamptz ); -- 现在展示索引 CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL; ### 5. 语义命名 使用有意义的表名/列名。名称对 LLM 而言带有意图。 **好：** `users`, `email`, `created_at`, `is_active` **坏：** `table1`, `col1`, `field`, `flag` --- ## 代码示例标准 ### SQL 格式化 sql -- 使用小写关键字，清晰的格式 CREATE INDEX CONCURRENTLY users_email_idx ON users(email) WHERE deleted_at IS NULL; -- 不要拥挤或全部大写 CREATE INDEX CONCURRENTLY USERS_EMAIL_IDX ON USERS(EMAIL) WHERE DELETED_AT IS NULL; ### 注释 - 解释“为什么”，而不是“是什么” - 突出性能影响 - 指出常见陷阱 ### 语言标签 - `sql` - 标准 SQL 查询 - `plpgsql` - 存储过程/函数 - `typescript` - 应用程序代码（需要时） - `python` - 应用程序代码（需要时） --- ## 何时包含应用程序代码 **默认：仅 SQL** 大多数规则应专注于纯 SQL 模式。这保持了示例的可移植性。 **在以下情况包含应用程序代码：** - 连接池配置 - 应用程序上下文中的事务管理 - ORM 反模式（Prisma/TypeORM 中的 N+1） - 预编译语句的使用 **混合示例格式：** `markdown **不正确（应用程序中的 N+1）：** typescript for (const user of users) { con