PDBD — Postgres DataBase Designer

Suite modular de skills para diseñar, revisar y documentar bases de datos PostgreSQL. Traduce requisitos funcionales a estructuras persistentes, relaciones, restricciones, índices, políticas de acceso, migraciones y pruebas SQL.

PDBD se limita deliberadamente al modelado de datos. Backend, frontend, APIs, workers e infraestructura se usan únicamente como contexto para decidir qué información debe persistirse y qué invariantes debe garantizar PostgreSQL.

Principios

• Modelo mínimo y comprensible, sin sobreingeniería.
• Sin requisitos futuros hipotéticos.
• Integridad y reglas de negocio expresadas con mecanismos nativos de PostgreSQL siempre que corresponda.
• SQL puro, ejecutable en DataGrip y sin metacomandos de psql.
• Archivos SQL organizados por dominio funcional, no por tabla ni por subskill.
• Sin lectura del proyecto ni persistencia de archivos sin autorización.
• Activación selectiva: normalmente cero a dos especialistas por tarea.

Skills incluidas

Skill	Responsabilidad
pdbd	Coordinación, diseño y generación del modelo PostgreSQL.
pdbd-business-rules	Reglas de negocio y su traducción a persistencia e integridad.
pdbd-catalogs	Catálogos, taxonomías, estándares, traducciones y seeds.
pdbd-concurrency	Reservas, cupos, saldos, idempotencia, locks y transacciones.
pdbd-consistency	Coherencia transversal de modelos, decisiones, reglas y SQL.
pdbd-ecommerce	Catálogo, inventario, pedidos, envíos y devoluciones.
pdbd-identity-access	Cuentas, credenciales, sesiones, MFA, recuperación y membresías.
pdbd-legal-ar	Implicancias argentinas sobre datos, conservación, evidencia y privacidad.
pdbd-payments-ar	Obligaciones, pagos, asignaciones, devoluciones y conciliación.
pdbd-performance	Planes de ejecución, índices, workload y capacidad PostgreSQL.
pdbd-reporting	Vistas, métricas, agregados y salidas con protección de privacidad.
pdbd-security	Roles, privilegios, RLS, aislamiento tenant y datos sensibles.

Flujo de modelado

1. Delimitar qué información debe persistir.
2. Identificar entidades, relaciones, cardinalidades y ciclos de vida.
3. Traducir reglas de negocio a invariantes persistentes.
4. Separar únicamente dominios reales.
5. Diseñar el mínimo conjunto de tablas y columnas.
6. Aplicar restricciones, claves e índices necesarios.
7. Revisar concurrencia, aislamiento, retención y seguridad cuando afecten los datos.
8. Simplificar antes de generar DDL.
9. Generar SQL documentado por dominio.
10. Validar integridad, simplicidad y orden de ejecución.

Estructura de trabajo

Cuando el usuario autoriza persistencia, la suite utiliza un briefcase/ compacto:

briefcase/
├── project-context.txt
├── model-draft.txt
├── decisions.md
├── domains/
├── reviews.md
├── brules.md
├── sql/
│   ├── ORDER.md
│   ├── models/
│   │   └── <domain>.sql
│   └── tests/
│       └── <domain>.sql
├── seeds/
├── migrations/
└── .work/

Los directorios domains/, seeds/ y migrations/ se crean únicamente cuando el entregable los necesita. .work/ contiene evidencia temporal y no es fuente de verdad.

Organización del SQL

Cada archivo briefcase/sql/models/<domain>.sql:

• representa un dominio funcional;
• documenta propósito, dependencias y orden de ejecución;
• agrupa tipos, tablas, constraints, índices, funciones, vistas, RLS y comentarios del dominio;
• usa nombres explícitos para constraints, índices, funciones y triggers;
• comenta validaciones, concurrencia, idempotencia y procesos complejos;
• referencia otros dominios mediante FK sin duplicar sus tablas.

Las pruebas correspondientes se guardan en briefcase/sql/tests/<domain>.sql.

Biblioteca de patrones

La coordinadora incluye patrones componibles para casos frecuentes, entre ellos:

• personas, documentos, direcciones y contactos;
• cuentas, contraseñas, sesiones, TOTP y recuperación;
• membresías, empleados, roles, planes y límites;
• agendas, recurrencias, disponibilidad y reservas;
• cajas, movimientos, transferencias, pagos y doble partida;
• productos, precios, inventario, pedidos, comprobantes y devoluciones;
• auditoría, consentimiento, retención, anonimización y documentos digitales;
• webhooks, importaciones, exportaciones y observaciones de salud.

Los patrones son referencias mínimas. No se copian completos ni obligan a crear una tabla por concepto.

Validación

El validador central acepta un briefcase, un directorio SQL o un archivo individual:

python pdbd/scripts/validate_sql_output.py briefcase/
python pdbd/scripts/validate_sql_output.py briefcase/sql/ --strict
python pdbd/scripts/validate_sql_output.py briefcase/sql/models/identity.sql

Comprueba, entre otros puntos:

• compatibilidad con DataGrip;
• ausencia de metacomandos psql y fences Markdown;
• encabezados y dependencias por dominio;
• documentación de tablas y procesos complejos;
• placeholders, secretos y datos reales;
• duplicación probable de objetos entre archivos.

Cada subskill incluye además su propio validador especializado.

Instalación

El repositorio contiene una carpeta por skill. Instalá la coordinadora pdbd y las subskills que quieras utilizar copiando cada carpeta completa al directorio de skills de tu agente.

La estructura interna de cada skill debe conservarse:

pdbd/
├── SKILL.md
├── agents/
├── references/
├── scripts/
└── templates/

No combines el contenido de varias skills dentro de una sola carpeta.

Uso recomendado

Invocá primero PDBD para coordinar el modelado. La coordinadora activará especialistas solo cuando cambien materialmente el diseño persistente.

Ejemplos de pedidos:

Diseña el modelo mínimo para actividades recurrentes con cupos,
excepciones y reservas sin solapamiento.

Revisa este EXPLAIN ANALYZE y propone índices PostgreSQL justificados.

Modela cuentas, sesiones opacas, TOTP y revocación global,
sin diseñar endpoints ni middleware.

Documentación interna

• MANIFEST.md: inventario de skills y archivos.
• VALIDATION.md: comprobaciones realizadas sobre la distribución.
• pdbd/references/database-only-scope.md: alcance exclusivo de base de datos.
• pdbd/references/sql-output-format.md: contrato de salida SQL.
• pdbd/templates/patterns/README.md: índice de patrones.

Contribuciones

Consultá CONTRIBUTING.md antes de proponer cambios. Las modificaciones deben mantener el alcance exclusivo de PostgreSQL, la simplicidad del modelo y los contratos compactos de artefactos.

Seguridad

No publiques esquemas, dumps, credenciales, datos personales ni planes de ejecución que contengan valores sensibles. Para informar un problema de seguridad, seguí SECURITY.md.

Licencia

Este repositorio no incluye todavía una licencia de distribución. Antes de publicarlo como proyecto abierto, añadí la licencia que refleje cómo querés permitir su uso, modificación y redistribución.