Base de datos

​

Organización recomendada

src/
├── db/
│   ├── tables/           # Definiciones Drizzle: *.table.ts
│   ├── backups/          # Respaldos SQL por DB_VERSION
│   ├── migrations/       # Cambios de estructura SQL
│   ├── commands/         # Cambios masivos de datos SQL
│   ├── config.db.ts      # Variables y configuración de PostgreSQL
│   ├── connection.db.ts  # Pool y esquema de Drizzle
│   └── *.db.ts           # Scripts de administración de la BD
├── queries/
│   └── [tabla]/
│       ├── [tabla].query.ts
│       └── [tabla]-join.query.ts
└── seeds/
    └── [tabla].seed.ts

​

Reglas para las tablas

1. Un archivo por tabla: usa [nombre].table.ts dentro de src/db/tables. Define el esquema con Drizzle ORM y exporta la tabla y los tipos necesarios.
2. Tres campos indispensables en absolutamente todas las tablas, incluso las tablas intermedias y de relaciones. Los nombres deben estar en inglés, tanto en TypeScript como en PostgreSQL:
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
   deletedAt: timestamp('deleted_at'),
   
3. Borrado lógico: deletedAt indica cuándo se eliminó un registro. Excluye registros eliminados de las consultas normales con isNull(tabla.deletedAt) cuando corresponda.
4. Actualización: defaultNow() solo inicializa updatedAt; al actualizar un registro, asigna explícitamente la nueva fecha o configura el mecanismo que lo haga.
5. Integridad y rendimiento: declara relaciones, índices y restricciones según las necesidades reales; cuando la unicidad dependa del borrado lógico, evalúa índices únicos parciales.
6. Una sola fuente para enums: deriva los valores utilizados por los DTO de los enums definidos en las tablas Drizzle; evita duplicar manualmente las listas de valores.

​

Acceso a datos: capa queries

• [tabla].query.ts contiene operaciones atómicas de una tabla (CRUD, filtros, paginación, conteos).
• [tabla]-join.query.ts contiene consultas relacionales, utilizando la tabla principal como base.
• Los services inyectan estas clases para acceder a la BD; no escriben consultas SQL ni instancian directamente la conexión.
• Registra en connection.db.ts las tablas que realmente existen en tu proyecto. No importes tablas de ejemplo que no estén implementadas.

​

Configuración y scripts

​

Versionado y seguridad

• DB_VERSION identifica versiones de respaldos, migraciones y comandos en los scripts que lo utilizan. Consulta backups, migrations y commands.
• Mantén separados los cambios de esquema (migrations) de las actualizaciones masivas de datos (commands).
• Realiza y verifica un respaldo antes de migrar, restaurar, reiniciar o ejecutar comandos destructivos; las operaciones sobre esquemas pueden destruir datos.
• Nunca incluyas credenciales reales ni archivos de respaldo sensibles en la documentación pública o commits de Git.