El modo de planificación del diseño de esquemas en Postgres te ayuda a definir entidades, restricciones, índices y migraciones antes de generar código, reduciendo reescrituras posteriores.
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:
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:
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.
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.
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:
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.
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_atdeleted_at solo si realmente necesitas borrados suaves y restauracióncreated_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.
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:
amount >= 0, status IN ('draft','paid','canceled') o rating BETWEEN 1 AND 5.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.
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.
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.
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:
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.
Fija expectativas desde temprano:
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.
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:
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:
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.
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:
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:
amount >= 0 o estados permitidos).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?
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:
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.
Planifica el esquema primero. Define un contrato de datos estable (tablas, claves, restricciones) para que los modelos y endpoints generados no necesiten renombrarse o reescribirse constantemente.
En la práctica: escribe tus entidades, relaciones y consultas principales, y bloquea las restricciones, índices y migraciones antes de generar código.
Escribe 2–3 frases que describan qué debe recordar la app y qué deben poder hacer los usuarios.
Luego lista:
Esto te da la claridad suficiente para diseñar tablas sin sobreconstruir.
Empieza listando los sustantivos que repites (user, project, invoice, task). Para cada uno, añade una frase: qué es y por qué existe.
Si no puedes describirlo claramente, probablemente acabarás con tablas vagas como items o misc y te arrepentirás después.
Usa una única estrategia de IDs consistente en todo el esquema.
Si necesitas un identificador legible, añade una columna única separada (por ejemplo, project_code) en vez de usarlo como PK.
Decídelo por relación según lo que los usuarios esperan y lo que debe preservarse.
Defaults comunes:
RESTRICT/NO ACTION cuando borrar el padre eliminaría registros importantes (por ejemplo, customer → orders).CASCADE cuando las filas hijas no tienen sentido sin el padre (por ejemplo, order → line items).Toma esta decisión temprano porque afecta el comportamiento de la API y los casos límite.
Pon reglas permanentes en la base de datos para que todo escritor (API, scripts, importaciones, herramientas admin) tenga que cumplirlas.
Prioriza:
Parte de los patrones de consulta reales, no de suposiciones.
Escribe de 5 a 10 consultas en lenguaje natural (filtros + orden) y luego crea índices para ellas:
status, user_id, created_atCrea una tabla de unión con dos claves foráneas y una restricción UNIQUE compuesta.
Patrón de ejemplo:
team_members(team_id, user_id, role, joined_at)UNIQUE (team_id, user_id) para evitar duplicadosEsto evita bugs sutiles como “¿por qué este usuario aparece dos veces?” y mantiene las consultas limpias.
Por defecto:
timestamptz para timestamps (menos sorpresas con zonas horarias)numeric(12,2) o enteros en céntimos para dinero (evita floats)CHECKMantén los tipos consistentes entre tablas (el mismo tipo para el mismo concepto) para que joins y validaciones sean previsibles.
Usa migraciones pequeñas y revisables y evita cambios rompientes en un solo paso.
Un camino seguro:
Decide también cómo manejarás datos seed/reference para que todos los entornos coincidan.
PRIMARY KEY en cada tablaFOREIGN KEY para cada columna “pertenece a”UNIQUE donde duplicados causen daño real (email, (team_id, user_id) en tablas de unión)CHECK para reglas simples (montos no negativos, estados permitidos)NOT NULL para campos obligatorios para que la fila tenga sentido(account_id, created_at))Evita indexar todo; cada índice penaliza INSERT y UPDATE.