Diseñar esquemas y consultas de bases de datos con Claude Code: guía práctica (2026)

¿Claude Code puede de verdad diseñar una BD y escribir consultas?

Sí, y lo hace muy bien, porque diseñar esquemas y escribir consultas son justo el tipo de trabajo para el que se creó una herramienta agéntica como Claude Code. Claude Code no es solo sugerencias tipo autocompletado: puede leer tus archivos y todo tu repositorio, ejecutar comandos en la terminal (psql, mongosh, correr pruebas), leer la salida e iterar para corregirse solo. Para las bases de datos, ese ciclo —"leer el contexto → generar DDL/consulta → ejecutarla → leer el resultado → ajustar"— es donde más brilla.

Esta guía se centra en los dos sistemas más comunes: PostgreSQL (relacional) y MongoDB (documento). El mismo enfoque sirve para ambos. Si apenas estás empezando y todavía no tienes claro qué es Claude Code, lee primero qué es Claude Code y para qué lo usas y luego vuelve aquí.

Una advertencia honesta de entrada: la IA es rápida con las bases de datos, pero no es automáticamente segura. Puede inventar nombres de columnas, elegir el tipo de dato equivocado para el dinero o generar una migración sin forma de deshacerla. Por eso toda esta guía se apoya en dos principios: concede solo acceso de solo lectura a producción y dale siempre a Claude una forma de comprobar su propio trabajo. Recorreremos el ciclo completo: conectar → diseñar el esquema → escribir consultas → índices y rendimiento → migraciones.

Configuración: conectar Claude Code a tu base de datos

Antes de pedirle nada a Claude, necesita "ver" de verdad tus datos. Hay tres formas, de la más segura a la más flexible:

Opción 1 - servidor MCP (recomendada, solo lectura)

MCP (Model Context Protocol) es la forma estándar en que Claude Code se conecta a herramientas externas, bases de datos incluidas. La documentación de MCP de Claude Code da un ejemplo directo de consultar datos "a partir de nuestra base de datos PostgreSQL" (documentación de MCP de Claude Code, Anthropic, 2026). El comando para añadir un servidor MCP por HTTP:

claude mcp add --transport http postgres-db https://your-mcp-endpoint

El detalle de seguridad decisivo: el servidor MCP de referencia para Postgres se describe como "acceso de solo lectura a la base de datos con inspección de esquema", es decir, solo lee e inspecciona la estructura, no escribe (modelcontextprotocol/servers, 2026; ese servidor se ha movido desde entonces al repositorio servers-archived). Eso es justo lo que quieres al dejar que la IA se acerque a tu BD: puede leer el esquema para entender el contexto, pero no puede borrar tus tablas por su cuenta. Si el MCP es nuevo para ti, mira qué es el MCP y cómo conectar herramientas externas a Claude Code.

Opción 2 - CLI psql / mongosh

Aún más simple: solo deja que Claude ejecute comandos por la terminal. Si ya tienes psql o mongosh configurados, Claude puede llamarlos directamente. Esto es flexible (también puede ejecutar comandos de escritura), pero es precisamente por eso que resulta más arriesgado: apúntalo solo a una BD de dev/local, nunca a una cadena de conexión de producción con permiso de escritura.

Opción 3 - pegar un archivo de esquema con @

Cuando todavía no estás lista para conectar una BD real, basta con entregarle a Claude tu archivo schema.sql o una descripción de tus tablas usando la sintaxis @:

Read @db/schema.sql and summarize the tables, primary keys, and relationships.
Then list 3 design risks you see.

Paso 1 - Diseña el esquema con Claude Code

El error más común es abrir Claude y escribir de inmediato "créame una tabla de usuarios". Si lo haces, recibes de vuelta un esquema genérico que la IA adivinó. La forma correcta es carga de trabajo primero: decide el tipo de carga antes y solo entonces deja que la IA construya las tablas.

Clasifica primero la carga de trabajo

Pregúntate (y dile a Claude) qué tipo de aplicación es esta, porque cada tipo se optimiza para una forma de datos distinta:

Usa el modo plan para que Claude lea antes de escribir

Activa el modo plan (pulsa Shift+Tab para cambiar de modo) y pídele a Claude que lea los requisitos, pregunte por cualquier cosa poco clara y solo entonces genere el DDL. Esto evita que se lance a crear tablas a las prisas sobre una suposición equivocada.

Patrón de prompt: declara invariantes, no columnas

En lugar de listar columnas, describe las reglas de negocio invariantes para que la propia IA defina la clave primaria, las restricciones únicas y las claves foráneas correctas:

Design a PostgreSQL schema for a small shop. Workload: OLTP.
Invariants:
- One email belongs to exactly one account (unique).
- An order must belong to an existing user (an orphan = a bug).
- Each order_items row records the price AT PURCHASE TIME, not the current price.
- Money must be exact, with no rounding error.
Ask me questions if anything is missing before writing the DDL.

Checklist relacional (para revisar el DDL que genera Claude)

• Nombra las entidades como sustantivos; nombra una tabla de unión según la relación que representa.
• La identidad estable va en la clave primaria; una regla de negocio única va en una restricción de unicidad.
• Usa una clave foránea siempre que un dato huérfano sería un bug.
• El dinero, las cantidades y el tiempo usan tipos exactos: nunca float para el dinero (usa numeric/decimal).
• Muchos a muchos: crea una tabla de unión dedicada y añade las columnas de metadatos útiles.
• Añade un índice solo para un predicado que hayas probado que necesitas (no indexes todo).

Un ejemplo real: un esquema mínimo de e-commerce que produjo Claude (con una línea que corregí, mira la nota):

CREATE TABLE users (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 email text NOT NULL UNIQUE,
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE orders (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 user_id bigint NOT NULL REFERENCES users(id),
 status text NOT NULL DEFAULT 'pending',
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 order_id bigint NOT NULL REFERENCES orders(id),
 product_id bigint NOT NULL,
 quantity int NOT NULL CHECK (quantity > 0),
 unit_price numeric(12,2) NOT NULL -- NOT float: money must be exact
);

La primera vez, Claude dejó unit_price como real (un float). Le hice cambiarlo a numeric(12,2): esta es exactamente la clase de bug que tienes que vigilar tú misma, porque la IA no siempre lo recuerda.

¿PostgreSQL o MongoDB? Elige por patrón de acceso

No elijas por preferencia, elige por cómo se leen y escriben los datos. Una tabla rápida:

La regla de oro de MongoDB cuando dudas entre incrustar y referenciar:

• Incrustar (Embed) cuando el dato hijo se lee/escribe junto con el padre y tiene un tamaño acotado (por ejemplo, una dirección de envío dentro de un pedido).
• Referenciar (Reference) cuando el dato crece sin límite, lo comparten muchos padres o necesita su propio ciclo de vida (por ejemplo, los comentarios de una publicación viral).

Paso 2 - Escribe y optimiza consultas con Claude Code

Aquí es donde Claude Code brilla: describes en lenguaje sencillo el resultado que quieres, él escribe la consulta, la explica y luego la optimiza. En SQL domina los JOIN, las subconsultas, los CTE y las funciones de ventana. Para MongoDB construye pipelines de agregación ($match → $group → $lookup).

Un ejemplo real: informe de ingresos mensuales. El prompt:

Write a Postgres query for total revenue per month in 2026,
counting only orders with status = 'paid'. Use a CTE for readability,
with a short explanation.

Claude devuelve:

WITH paid_items AS (
 SELECT o.created_at, oi.quantity * oi.unit_price AS line_total
 FROM orders o
 JOIN order_items oi ON oi.order_id = o.id
 WHERE o.status = 'paid'
 AND o.created_at >= '2026-01-01'
 AND o.created_at < '2027-01-01'
)
SELECT date_trunc('month', created_at) AS month,
 SUM(line_total) AS revenue
FROM paid_items
GROUP BY 1
ORDER BY 1;

Salida al ejecutar (datos de ejemplo):

 month | revenue
--------------------+-----------
 2026-01-01 00:00:00 | 154200.00
 2026-02-01 00:00:00 | 187650.50
 2026-03-01 00:00:00 | 203110.00

En MongoDB la misma idea es un pipeline: $match filtra los pedidos paid, $unwind despliega el array de ítems, $group agrupa por mes. Pídele a Claude que lo escriba y luego explique cada etapa: la forma más rápida de obtener a la vez una consulta y su comprensión.

Advertencia importante: vuelve a leer siempre la consulta que escribió Claude antes de ejecutarla contra datos reales. Un UPDATE/DELETE al que le falta su WHERE —que la IA puede producir por error— puede borrar una tabla entera. Léela, entiéndela y solo entonces pulsa Enter.

Paso 3 - Índices y rendimiento con EXPLAIN ANALYZE

Que una consulta funcione correctamente no basta, tiene que funcionar rápido. Haz que Claude ejecute EXPLAIN ANALYZE (Postgres) o .explain() (Mongo), lea el plan y luego sugiera un índice, en el lugar correcto y no a ciegas.

Run EXPLAIN ANALYZE for the revenue query above.
If you see a Seq Scan on orders, suggest a suitable index and explain why.

En una tabla orders grande, el plan inicial suele mostrar un Seq Scan porque filtra por status y created_at. Añade el índice adecuado:

CREATE INDEX idx_orders_status_created
 ON orders (status, created_at);

Ejecútala de nuevo y el plan cambia a un Index Scan, y el tiempo de la consulta baja de forma notable. El punto donde quieres la ayuda de Claude es elegir el orden de las columnas en un índice compuesto para que coincida con el predicado: aquí es donde suelen equivocarse los desarrolladores más nuevos.

El principio de indexación que evita el exceso de índices (algo que el propio Claude tiende a exagerar): indexa solo las claves foráneas, las columnas por las que filtras/ordenas con frecuencia y las restricciones de unicidad. Cada índice que añades ralentiza las escrituras y cuesta almacenamiento, así que no indexes "por si acaso". Si le dices a Claude "añade índices para que sea más rápido", tiende a pasarse: pídele que solo proponga índices con un predicado demostrable.

Paso 4 - Migraciones seguras con Claude Code

Cambiar el esquema en un sistema en vivo es la tarea más propensa a incidentes que existe. Un proceso seguro para cuando dejas que Claude genere una migración:

1. Incluye siempre un rollback. Toda migración "up" debe tener una "down" que le corresponda. Pídele a Claude que escriba ambas y explique cómo deshacer el cambio.
2. Prueba primero en una copia. Ejecuta la migración en una BD de dev o en un snapshot de producción, nunca directamente contra producción.
3. Compara antes/después. Cuenta las filas y revisa unos cuantos registros de muestra antes y después para asegurarte de que no se perdió ningún dato.
4. Revisa el diff con un subagente. Haz que un subagente revise la migración como un PR independiente, buscando operaciones destructivas (DROP, cambiar un tipo de dato) que no tengan un paso de seguridad.

Las buenas prácticas de Anthropic resumen este principio en una sola frase: "dale a Claude una forma de verificar su trabajo" (buenas prácticas de Claude Code, Anthropic, 2026). Para las bases de datos, "verificar" significa algo concreto: correr pruebas, ejecutar EXPLAIN y comparar el recuento de filas antes y después, y no creer a la IA cuando dice que está "listo".

Una barrera de seguridad que vale la pena montar: usa un hook de permisos para impedir que Claude escriba por su cuenta en el directorio migrations/, o para bloquear comandos DDL destructivos, obligando a que todo cambio pase por tu revisión. Para más sobre cómo ajustar los permisos de forma segura, mira cómo hacer una auditoría de seguridad con Claude Code.

Trampas reales cuando dejas que la IA maneje bases de datos (lee esto antes de producción)

Esta sección es la que más importa, y casi ninguna documentación lo dice en voz alta. La IA es rápida con las BD, pero aquí es donde de verdad se equivoca; yo he caído en todas estas:

• Inventar nombres de columnas/tablas. A veces Claude referencia una columna que no existe porque adivinó el esquema. Deja siempre que lea el esquema real (vía MCP o @schema.sql) antes de escribir una consulta.
• Tipo equivocado para el dinero. Recurre muy a menudo a float/real para los precios, lo que provoca errores de redondeo que se acumulan. Exige numeric/decimal.
• Exceso de índices. Esparcir índices por todas partes ralentiza las escrituras sin acelerar de verdad las lecturas.
• Migraciones sin rollback. Generar el up pero olvidar el down, dejándote atascada cuando necesitas deshacer.
• Consultas N+1 o de escaneo completo. Escribir un bucle que consulta registro por registro en vez de un único JOIN, o dejar caer una condición de filtro.

Tres reglas innegociables: (1) concede acceso de solo lectura a producción únicamente: deja que la IA lea, nunca que escriba; (2) todo cambio de esquema pasa por un PR + pruebas, nunca se aplica directamente; (3) verifica con EXPLAIN + comparación de recuento de filas, no confíes en el "listo". Haz estas tres cosas y usar IA en tu BD es perfectamente seguro.

Ve más rápido con la skill ak-databases (AgentKit)

Si te descubres reescribiendo el prompt de "carga primero, declara los invariantes, incluye el checklist" cada vez, hay un atajo honesto: el AgentKit Engineer Kit (que contiene la skill ak-databases) empaqueta exactamente la columna vertebral de este artículo. La skill ak-databases cubre el diseño de esquemas OLTP/OLAP, la escritura de consultas Postgres/Mongo, la agregación, la indexación y las migraciones, junto con scripts como db_migrate.py, db_backup.py y db_performance_check.py. Solo escribes con naturalidad —"diseña un esquema para..."— y la skill se activa sola, así que no tienes que memorizar el patrón del prompt.

Preguntas frecuentes (FAQ)

¿Claude Code puede conectarse directamente a una base de datos?

Sí, de dos formas: un servidor MCP (recomendado, normalmente solo lectura) o dejar que Claude ejecute comandos psql/mongosh por la terminal. Cuando aún no quieres conectar una BD real, puedes pegar el archivo de esquema usando la sintaxis @.

¿Claude Code ejecutará consultas contra producción por su cuenta?

No deberías darle esa capacidad. Concede solo una conexión de solo lectura a producción y mantén todas las operaciones de escritura/DDL en una BD de dev o detrás de un PR revisado. Usa un hook de permisos para bloquear los comandos destructivos.

¿Debería elegir PostgreSQL o MongoDB?

Elige por patrón de acceso, no por preferencia. PostgreSQL para transacciones que necesitan restricciones estrictas y para informes agregados; MongoDB para datos anidados que se leen/escriben como una unidad. Las transacciones de dinero deberían ser casi siempre PostgreSQL.

¿Claude Code puede escribir migraciones?

Sí, pero tienes que pedirle que escriba también el paso de rollback (down), probar primero en una copia y comparar el recuento de filas antes y después de ejecutarla. No apliques una migración generada por IA directamente en producción.

¿Es seguro dejar que la IA maneje bases de datos?

Es seguro si sigues tres reglas: solo lectura en producción, todo cambio por un PR + pruebas, y verificación con EXPLAIN ANALYZE + comparación de recuento de filas. El riesgo real viene de conceder acceso de escritura y confiar en la IA sin comprobar.

¿Tengo que comprar el Engineer Kit?

No. Todo el flujo de trabajo de este artículo funciona con Claude Code puro. La skill ak-databases solo lo hace más rápido y consistente cuando trabajas con BD de forma habitual o en equipo.

Conclusión y próximos pasos

Para recapitular los cuatro pasos: conecta la BD (mejor MCP de solo lectura) → diseña el esquema según la carga de trabajo → escribe y optimiza consultas con verificación → migra con un rollback. La clave no es dejar que la IA lo haga todo por ti, sino darle suficiente contexto y siempre una forma de comprobar su propio trabajo. Una vez listo el esquema, el siguiente paso lógico es conectar la BD a tu capa de API: mira cómo construir un backend y una API con Claude Code. Y si quieres acelerar la parte de diseño de la BD, puedes probar la skill ak-databases del Engineer Kit.