{
  "id": "ai-rules-for-postgresql-apps",
  "type": "rules",
  "category": "rules",
  "locale": "es",
  "url": "/es/rules/ai-rules-for-postgresql-apps",
  "title": "Reglas de Codificación de IA para Aplicaciones con PostgreSQL",
  "description": "Reglas de AGENTS.md para aplicaciones respaldadas por PostgreSQL que cubren seguridad de consultas, disciplina de migraciones, convenciones de indexación y prevención de consultas N+1 por parte de agentes.",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex",
    "Windsurf"
  ],
  "stack": [
    "PostgreSQL",
    "TypeScript",
    "Next.js"
  ],
  "tags": [
    "agents-md",
    "postgres",
    "typescript",
    "security",
    "conventions"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "Coloca esto en la raíz de tu repositorio como `AGENTS.md`. Se aplica a cualquier proyecto donde PostgreSQL sea el almacén de datos principal, ya sea accedido a través de Prisma, Drizzle, `postgres.js` o SQL puro.\n\n## AGENTS.md\n\n```md title=\"AGENTS.md\"\n# Project Rules — PostgreSQL Apps\n\n## Hard rules — data safety\n- NEVER generate SQL that concatenates user input into a query string. Always use\n  parameterised queries (`$1`, `$2` placeholders) or the ORM's parameter binding.\n  SQL injection via agent-generated queries is a real attack vector.\n- NEVER run `DROP TABLE`, `TRUNCATE`, or `DELETE FROM <table>` without a `WHERE`\n  clause in application code. These must be wrapped in a transaction that can be\n  rolled back, and must require explicit developer confirmation before execution.\n- NEVER write a migration that removes a column without first deploying a version of\n  the application that stops reading that column. Column removal is a two-deploy\n  operation: (1) stop reading; (2) drop.\n- All schema changes must be applied via migration files (Drizzle Kit, Flyway,\n  `migrate`, or Prisma Migrate). Never apply schema changes by running `ALTER TABLE`\n  directly against production.\n\n## Query conventions\n- Every query that returns a list MUST have a `LIMIT`. There is no acceptable reason\n  for a user-facing endpoint to return an unbounded result set.\n- Use `EXPLAIN ANALYZE` to check query plans for new queries on tables with more than\n  10,000 rows before merging. Agents should output the plan in a comment block when\n  writing a non-trivial query.\n- Avoid `SELECT *`. Name every column you need. This makes queries self-documenting\n  and prevents accidental exposure of sensitive columns (hashed passwords, tokens).\n- N+1 patterns are forbidden. If you load a list of records and then query related\n  data per row in a loop, refactor to a single JOIN query or a batched `IN` query.\n- Use `JOIN` instead of correlated subqueries for relation lookups — correlated\n  subqueries run once per row and are almost always slower.\n\n## Indexing rules\n- Every foreign key column MUST have an index. PostgreSQL does not create these\n  automatically (unlike MySQL). Missing FK indexes cause sequential scans on join.\n- Columns used in `WHERE` clauses on high-read tables should have indexes. When\n  adding a query that filters by a new column, check whether an index exists and\n  add one in the same migration if it does not.\n- Use partial indexes (`WHERE deleted_at IS NULL`) for soft-delete patterns — they\n  are far smaller and faster than full-table indexes when most rows are soft-deleted.\n- Never create an index on a column with very low cardinality (e.g. a boolean\n  `is_active` with 90% `true`). PostgreSQL will ignore the index and scan anyway.\n\n## Connection and pooling\n- Import the database client from `src/lib/db.ts` (the singleton or pool). Never\n  instantiate a new client per request — this exhausts connections instantly under load.\n- In serverless environments (Next.js API routes, Edge Functions), use a connection\n  pooler (PgBouncer, Neon connection pooling, Supabase pgbouncer mode) between the\n  application and PostgreSQL. Direct connections from serverless are not sustainable.\n- Set `statement_timeout` and `lock_timeout` on the connection or session for\n  long-running operations to prevent them from blocking the entire application.\n\n## Transactions\n- Any operation that writes to more than one table must be wrapped in a transaction.\n  Partial writes leave the database in an inconsistent state.\n- Keep transactions as short as possible. Do not make network requests (HTTP calls,\n  external APIs) inside a transaction — this holds locks for the duration of the\n  network call.\n\n## Definition of done\n- No string-interpolated SQL in the codebase (`grep -r \"query\\`\" src/` should return\n  only parameterised template tag usage, not concatenation).\n- All new tables have primary key and foreign key indexes.\n- All `findMany` / `SELECT` queries have `LIMIT`.\n- Migration files are committed and named descriptively.\n- `tsc --noEmit` passes (typed query results match schema types).\n```\n\n## Por qué estas reglas\n\n- **Nunca SQL concatenado con cadenas** es la regla fundamental. Las consultas parametrizadas no son solo una buena práctica, son la única defensa contra la inyección SQL, y los agentes bajo presión de tiempo concatenarán cuando no sepan cómo expresar una consulta con la sintaxis de parámetros de un ORM específico.\n- **La eliminación de columnas es una operación de dos despliegues** evita el error más común en migraciones sin tiempo de inactividad. Si la aplicación aún lee una columna cuando la migración la elimina, cada solicitud en vuelo en el momento de la migración falla. Los agentes no razonan naturalmente sobre las ventanas de despliegue al generar cambios de esquema.\n\n## Buen ajuste\n\n- Cualquier aplicación de producción que use PostgreSQL donde la integridad de datos y el rendimiento de consultas importen: aplicaciones SaaS, plataformas de contenido, backends de comercio electrónico, pipelines de análisis.\n\n## No es adecuado\n\n- Aplicaciones basadas en SQLite o proyectos donde la base de datos es verdaderamente efímera (fixtures de prueba, semillas de desarrollo local) — la disciplina de migraciones y las reglas de indexación son una sobrecarga innecesaria."
}