Modo de planificación del diseño de esquemas en Postgres: enfoque paso a paso

Por qué planificar tu esquema de Postgres antes de generar código

Si construyes endpoints y modelos antes de que la forma de la base de datos esté clara, normalmente terminas reescribiendo las mismas funciones dos veces. La app funciona para una demo, luego llegan datos reales y casos límite y todo empieza a sentirse frágil.

La mayoría de las reescrituras provienen de tres problemas previsibles:

• Las entidades no están claras (se nombraron o agruparon mal).
• No se aplicaron reglas (faltaban restricciones).
• Los problemas de rendimiento aparecen tarde (los índices se añadieron después de que los usuarios se quejaran).

Cada uno fuerza cambios que se propagan por el código, las pruebas y las apps cliente.

Planificar tu esquema de Postgres significa decidir el contrato de datos primero y luego generar código que lo respete. En la práctica, eso equivale a anotar entidades, relaciones y las pocas consultas que importan, y después elegir restricciones, índices y una estrategia de migraciones antes de que cualquier herramienta scaffoldee tablas y CRUD.

Esto importa aún más cuando usas una plataforma de generación rápida como Koder.ai, donde puedes generar mucho código rápidamente. La generación rápida es estupenda, pero es mucho más fiable cuando el esquema está asentado. Tus modelos y endpoints generados necesitarán menos ediciones después.

Esto es lo que suele fallar cuando saltas la planificación:

• Una tabla “User” se convierte silenciosamente en usuarios, admins y equipos mezclados.
• Aparecen registros duplicados porque nadie hace cumplir unicidad.
• Los borrados rompen historial porque nunca se decidió el comportamiento de las referencias.
• Una página de lista popular se vuelve lenta porque no se planificó el índice correcto.

Un buen plan de esquema es simple: una descripción en lenguaje natural de tus entidades, un borrador de tablas y columnas, las restricciones e índices clave y una estrategia de migraciones que te permita cambiar las cosas de forma segura a medida que el producto crece.

Empieza por las necesidades de datos, no por las tablas

La planificación del esquema funciona mejor cuando empiezas por lo que la app debe recordar y por lo que las personas deben poder hacer con esos datos. Escribe el objetivo en 2 o 3 frases en lenguaje claro. Si no puedes explicarlo de forma simple, probablemente crearás tablas extras que no necesitas.

A continuación, céntrate en las acciones que crean o cambian datos. Esas acciones son la fuente real de tus filas y revelan qué debe validarse. Piensa en verbos, no en sustantivos.

Por ejemplo, una app de reservas podría necesitar crear una reserva, reprogramarla, cancelarla, reembolsarla y enviar mensajes al cliente. Esos verbos sugieren rápidamente qué debe almacenarse (franjas horarias, cambios de estado, importes) antes de que nombres una tabla.

Captura también tus rutas de lectura, porque las lecturas guían la estructura y el indexado más adelante. Lista las pantallas o informes que la gente usará y cómo cortan los datos: “Mis reservas” ordenadas por fecha y filtradas por estado, búsqueda administrativa por nombre de cliente o referencia de reserva, ingresos diarios por ubicación y una vista de auditoría de quién cambió qué y cuándo.

Finalmente, anota las necesidades no funcionales que cambian las decisiones de esquema, como historial de auditoría, borrados suaves, separación multi-tenant o reglas de privacidad (por ejemplo, limitar quién puede ver datos de contacto).

Si planeas generar código después, estas notas se convierten en prompts sólidos. Dejan claro qué es obligatorio, qué puede cambiar y qué debe ser buscable. Si usas Koder.ai, escribir esto antes de generar cualquier cosa hace que el Modo de Planificación sea mucho más efectivo porque la plataforma trabaja con requisitos reales en lugar de suposiciones.

Define entidades y relaciones en lenguaje claro

Antes de tocar tablas, escribe una descripción simple de lo que tu app almacena. Empieza listando los sustantivos que repites: user, project, message, invoice, subscription, file, comment. Cada sustantivo es una candidata a entidad.

Luego añade una frase por entidad que responda: qué es y por qué existe. Por ejemplo: “Un Project es un espacio de trabajo que crea un usuario para agrupar trabajo e invitar a otros.” Esto evita tablas vagas como data, items o misc.

La propiedad es la siguiente gran decisión y afecta casi todas las consultas que escribas. Para cada entidad, decide:

• quién la crea,
• quién puede verla,
• quién puede cambiarla,
• qué pasa cuando se elimina el propietario (conservar, transferir o borrar).

Ahora decide cómo identificarás los registros. Los UUID son ideales cuando los registros pueden crearse desde muchos sitios (web, móvil, jobs) o cuando no quieres IDs previsibles. Los bigint son más pequeños y rápidos. Si necesitas un identificador legible por humanos, mantenlo separado (por ejemplo, un project_code corto y único dentro de una cuenta) en lugar de forzarlo a ser la clave primaria.

Finalmente, escribe las relaciones en palabras antes de diagramar nada: un usuario tiene muchos proyectos, un proyecto tiene muchos mensajes y los usuarios pueden pertenecer a muchos proyectos. Marca cada enlace como obligatorio u opcional, por ejemplo “un mensaje debe pertenecer a un proyecto” vs “una factura puede pertenecer a un proyecto”. Estas frases serán tu fuente de verdad para la generación de código más tarde.

Traduce entidades en tablas y columnas

Una vez que las entidades estén claras en lenguaje natural, convierte cada una en una tabla con columnas que reflejen hechos reales que necesitas almacenar.

Empieza con nombres y tipos que puedas mantener. Elige patrones consistentes: nombres de columnas en snake_case, el mismo tipo para la misma idea y claves primarias predecibles. Para timestamps, prefiere timestamptz para que las zonas horarias no te sorprendan. Para dinero, usa numeric(12,2) (o almacena céntimos como entero) en vez de floats.

Para campos de estado, usa un enum de Postgres o una columna text con una restricción CHECK para que los valores permitidos estén controlados.

Decide qué es requerido vs opcional traduciendo reglas a NOT NULL. Si un valor debe existir para que la fila tenga sentido, hazlo requerido. Si es verdaderamente desconocido o no aplicable, permite nulls.

Un conjunto práctico de columnas por defecto para planear:

• id (uuid o bigint, elige un enfoque y sé consistente)
• created_at y updated_at
• deleted_at solo si realmente necesitas borrados suaves y restauración
• created_by cuando necesites una pista de auditoría clara de quién hizo qué

Las relaciones muchos-a-muchos casi siempre deberían convertirse en tablas de unión. Por ejemplo, si varios usuarios pueden colaborar en una app, crea app_members con app_id y user_id, luego aplica unicidad sobre el par para que no puedan ocurrir duplicados.

Piensa en el historial desde temprano. Si sabes que necesitarás versionado, planifica una tabla inmutable como app_snapshots, donde cada fila es una versión guardada ligada a apps por app_id y con created_at.

Añade restricciones que protejan tus datos

Las restricciones son las barandillas de tu esquema. Decide qué reglas deben ser verdad sin importar qué servicio, script o herramienta admin toque la base de datos.

Empieza por identidad y relaciones. Cada tabla necesita una clave primaria y cualquier campo “pertenece a” debería ser una llave foránea real, no solo un integer que esperas que coincida.

Luego añade unicidad donde los duplicados causarían daño real, como dos cuentas con el mismo email o dos líneas con el mismo (order_id, product_id).

Restricciones de alto valor para planear temprano:

• Primary keys: elige un estilo consistente (UUIDs o bigints) para que los joins sean previsibles.
• Foreign keys: hace la relación explícita y evita filas huérfanas.
• Unique constraints: úsalas para identidad de negocio (email, username) y reglas de “solo uno de estos”.
• Check constraints: reglas baratas como amount >= 0, status IN ('draft','paid','canceled') o rating BETWEEN 1 AND 5.
• Not null: exige campos que son obligatorios en la vida real, no solo “usualmente llenados”.

El comportamiento de cascada es donde la planificación te ahorra problemas luego. Pregunta qué esperan realmente las personas. Si se elimina un cliente, sus pedidos normalmente no deberían desaparecer. Eso apunta a restringir borrados y conservar historial. Para datos dependientes como las líneas de pedido, la cascada del pedido a las líneas puede tener sentido porque las líneas no tienen significado sin el padre.

Cuando luego generes modelos y endpoints, estas restricciones serán requisitos claros: qué errores manejar, qué campos son obligatorios y qué casos límite son imposibles por diseño.

Planifica índices a partir de consultas reales

Los índices deben responder a una pregunta: qué necesita ser rápido para usuarios reales.

Empieza con las pantallas y llamadas API que esperas enviar primero. Una página de lista que filtra por estado y ordena por más recientes tiene necesidades distintas a una página de detalle que carga registros relacionados.

Anota de 5 a 10 patrones de consulta en lenguaje natural antes de escoger cualquier índice. Por ejemplo: “Mostrar mis facturas de los últimos 30 días, filtrar por pagadas/no pagadas, ordenar por created_at”, o “Abrir un proyecto y listar sus tareas por due_date”. Esto mantiene las elecciones de índices ancladas al uso real.

Un buen primer conjunto de índices suele incluir columnas de clave foránea usadas para joins, columnas de filtro comunes (como status, user_id, created_at) y uno o dos índices compuestos para consultas multi-filtro estables, como (account_id, created_at) cuando siempre filtras por account_id y luego ordenas por tiempo.

El orden en un índice compuesto importa. Pon la columna por la que filtras con más frecuencia (y que es más selectiva) primero. Si filtras por tenant_id en cada petición, a menudo pertenece al frente de muchos índices.

Evita indexar todo “por si acaso”. Cada índice añade trabajo en INSERT y UPDATE, y eso puede perjudicar más que una consulta rara algo más lenta.

Planifica la búsqueda de texto por separado. Si solo necesitas coincidencias simples “contains”, ILIKE puede ser suficiente al principio. Si la búsqueda es central, planea full-text (tsvector) temprano para no rediseñar después.

Decide tu estrategia de migraciones antes de generar código

Un esquema no queda “hecho” cuando creas las primeras tablas. Cambia cada vez que añades una función, arreglas un error o aprendes más sobre tus datos. Si decides la estrategia de migraciones desde el inicio, evitarás reescrituras dolorosas tras la generación de código.

Mantén una regla simple: cambia la base de datos en pasos pequeños, una función a la vez. Cada migración debe ser fácil de revisar y segura de ejecutar en todos los entornos.

Cómo manejar cambios rompientes de forma segura

La mayoría de los rompimientos vienen de renombrar o eliminar columnas, o cambiar tipos. En vez de hacerlo todo de golpe, planifica un camino seguro:

• Añade columnas nuevas primero (nullable si hace falta) y luego rellena los datos.
• Si la app debe seguir funcionando durante el cambio, usa escritura dual por un breve periodo (escribir en campos viejo y nuevo).
• Cambia las lecturas al campo nuevo y luego limpia la columna antigua en una migración posterior.

Esto requiere más pasos, pero en la práctica es más rápido porque reduce caídas y parches de emergencia.

Los datos seed también forman parte de las migraciones. Decide qué tablas de referencia son “siempre presentes” (roles, estados, países, tipos de plan) y hazlas predecibles. Pon inserts y updates para estas tablas en migraciones dedicadas para que cada desarrollador y cada despliegue obtengan los mismos resultados.

Reglas de consistencia entre local, dev y prod

Fija expectativas desde temprano:

• Mismas migraciones, mismo orden, en todos lados.
• No hay hotfixes manuales en producción sin una migración que los refleje.
• Cada migración tiene una historia clara hacia adelante y un plan de rollback realista.

Los rollbacks no siempre son una migración “down” perfecta. A veces el mejor rollback es restaurar desde una copia de seguridad. Si usas Koder.ai, también vale la pena decidir cuándo confiar en snapshots y restauraciones para recuperaciones rápidas, sobre todo antes de cambios riesgosos.

Un ejemplo sencillo que puedes copiar y ajustar

Imagina una pequeña app SaaS donde la gente se une a equipos, crea proyectos y rastrea tareas.

Empieza listando las entidades y solo los campos que necesitas el primer día:

• users: id, email, full_name, created_at
• teams: id, org_id, name, created_at
• team_members: team_id, user_id, role, joined_at
• projects: id, team_id, name, status, created_at
• tasks: id, project_id, assignee_user_id (nullable), title, state, due_date (nullable), created_at

Las relaciones son directas: un equipo tiene muchos proyectos, un proyecto tiene muchas tareas y los usuarios se unen a equipos a través de team_members. Las tareas pertenecen a un proyecto y pueden asignarse a un usuario.

Ahora añade algunas restricciones que previenen bugs que típicamente se detectan demasiado tarde:

• Haz users.email único (insensible a mayúsculas si usas citext).
• Haz los nombres de equipo únicos dentro de la misma org: UNIQUE (org_id, name) en teams.
• Evita membresías duplicadas: UNIQUE (team_id, user_id) en team_members.

Los índices deben coincidir con las pantallas reales. Por ejemplo, si la lista de tareas filtra por proyecto y estado y ordena por más recientes, planifica un índice como tasks (project_id, state, created_at DESC). Si “Mis tareas” es una vista clave, un índice como tasks (assignee_user_id, state, due_date) puede ayudar.

Para migraciones, mantén la primera versión segura y aburrida: crea tablas, claves primarias, claves foráneas y las restricciones únicas esenciales. Un cambio útil posterior es algo que añades cuando el uso lo valide, como introducir borrado suave (deleted_at) en tasks y ajustar índices para ignorar filas borradas.

Errores comunes y cómo evitarlos

La mayoría de las reescrituras ocurren porque el primer esquema carece de reglas y detalles de uso real. Un buen pase de planificación no busca diagramas perfectos. Busca trampas temprano.

Un error común es mantener reglas importantes solo en el código de la aplicación. Si un valor debe ser único, presente o estar dentro de un rango, la base de datos también debería hacerlo cumplir. De lo contrario, un job en background, un endpoint nuevo o una importación manual pueden saltarse tu lógica.

Otro fallo frecuente es tratar los índices como un problema posterior. Añadirlos después del lanzamiento suele convertirse en conjeturas, y puedes acabar indexando lo incorrecto mientras la consulta lenta real está en un join o en un filtro por estado.

Las tablas muchos-a-muchos también causan bugs silenciosos. Si tu tabla de unión no previene duplicados, puedes almacenar la misma relación dos veces y perder horas debugeando “¿por qué este usuario tiene dos roles?”.

También es fácil crear tablas primero y luego darte cuenta de que necesitas logs de auditoría, borrados suaves o historial de eventos. Esas adiciones se propagan a endpoints e informes.

Finalmente, las columnas JSON son tentadoras para datos “flexibles”, pero eliminan comprobaciones y hacen más difícil el indexado. JSON está bien para payloads realmente variables, no para campos de negocio centrales.

Antes de generar código, corre esta lista de corrección rápida:

• Mueve reglas clave a restricciones: NOT NULL, CHECK, UNIQUE y foreign keys.
• Escribe 3 a 5 consultas reales y crea índices para esas, no para “quizás más tarde”.
• Añade un UNIQUE compuesto en tablas de unión (por ejemplo, user_id + role_id).
• Decide temprano si necesitas historial de auditoría y modelalo como su propia tabla.
• Usa JSON para atributos raros u opcionales y promueve campos importantes a columnas.

Lista de verificación rápida antes de generar modelos y endpoints

Haz una pausa y asegúrate de que el plan sea lo suficientemente completo como para generar código sin perseguir sorpresas. La meta no es la perfección. Es detectar las lagunas que causan reescrituras: relaciones faltantes, reglas poco claras e índices que no coinciden con el uso real.

Usa esto como un chequeo pre-vuelo rápido:

• Para cada entidad, escribe una frase sobre quién la posee (user, org, system) y qué significa “borrado” (hard delete, soft delete, archivado).
• Para cada tabla, confirma tipo de columna, requerido vs opcional, defaults y cómo se establecen timestamps (por la app o por la base de datos).
• Escribe las reglas que nunca deben romperse: claves primarias, claves foráneas, reglas de unicidad y algunos checks simples (como amount >= 0 o estados permitidos).
• Elige tus 3 a 5 pantallas o llamadas API principales y lista exactamente los filtros y el orden que necesitan. Asegúrate de que tus índices coincidan.
• Esboza las primeras migraciones: esquema inicial, qué datos deben existir el primer día (seed rows) y un cambio que esperas pronto (añadir un estado, separar un campo nombre, introducir orgs).

Una prueba de sentido común: imagina que un compañero se incorpora mañana. ¿Podría construir los primeros endpoints sin preguntar “¿esto puede ser null?” o “¿qué pasa al eliminar?” cada hora?

Próximos pasos: ir del plan al código con menos reescrituras

Una vez que el plan lea claro y los flujos principales tengan sentido en papel, transmútalo a algo ejecutable: un esquema real más migraciones.

Empieza con una migración inicial que cree tablas, tipos (si usas enums) y las restricciones imprescindibles. Mantén la primera pasada pequeña pero correcta. Carga algo de seed data y ejecuta las consultas que tu app necesitará. Si un flujo se siente incómodo, corrige el esquema mientras el historial de migraciones aún es corto.

Genera modelos y endpoints solo después de poder probar unas pocas acciones end-to-end con el esquema en su lugar (crear, actualizar, listar, borrar, más una acción real de negocio). La generación de código es más rápida cuando tablas, claves y nombres están lo bastante estables como para no renombrarlo todo al día siguiente.

Un bucle práctico que mantiene bajas las reescrituras:

• Actualiza el plan cuando aprendes algo nuevo en las pruebas.
• Añade una nueva migración (evita editar las antiguas después de que otros las usen).
• Regenera modelos y endpoints si el esquema cambió.
• Vuelve a ejecutar los mismos flujos y consultas para confirmar que nada se rompió.
• Añade campos agradables y índices extra solo después de que las rutas principales estén sólidas.

Decide temprano qué validas en la base de datos vs en la capa API. Coloca reglas permanentes en la base de datos (foreign keys, unique constraints, check constraints). Mantén reglas suaves en la API (feature flags, límites temporales y lógica cross-table compleja que cambia a menudo).

Si usas Koder.ai, un enfoque sensato es acordar entidades y migraciones en Modo de Planificación primero y luego generar tu backend en Go y PostgreSQL. Cuando un cambio va mal, snapshots y rollback pueden ayudarte a volver a una versión conocida mientras ajustas el plan del esquema.