Migraciones

Motoko Base usa Drizzle Kit para gestionar las migraciones de base de datos. El esquema se define en TypeScript (src/lib/db/schema/); Drizzle genera archivos SQL de migración y los aplica a tu base Postgres.

Los tres comandos están definidos en package.json:

"db:generate": "drizzle-kit generate",
"db:migrate": "drizzle-kit migrate",
"db:studio": "drizzle-kit studio"

La configuración vive en drizzle.config.ts:

export default defineConfig({
  schema: "./src/lib/db/schema/schema.ts",
  out: "./drizzle/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

DATABASE_URL debe estar definida en .env antes de ejecutar cualquier comando. Con Supabase, usa la conexión directa (puerto 5432) si las migraciones fallan a través del transaction pooler.

pnpm db:generate

Genera un nuevo archivo de migración a partir de las diferencias entre tu esquema TypeScript y el último snapshot de migración.

When to use

• Tras añadir o editar una tabla en src/lib/db/schema/
• Tras añadir columnas, índices, claves foráneas o constraints
• Tras exportar un nuevo archivo de esquema desde schema.ts

When not to use

• Para aplicar migraciones — usa db:migrate en su lugar
• Para explorar datos — usa db:studio en su lugar
• En un clone fresco sin cambios de esquema — no hay nada nuevo que generar

What it does

1. Lee src/lib/db/schema/schema.ts y todas las tablas exportadas
2. Compara con el último snapshot en drizzle/migrations/
3. Crea una carpeta nueva bajo drizzle/migrations/ con:
   • migration.sql — el SQL a ejecutar
   • snapshot.json — estado del esquema para el próximo diff

Example

Añadiste una tabla notes al esquema:

pnpm db:generate

Salida (ejemplo):

drizzle/migrations/20260824120000_some_name/migration.sql

Revisa el SQL generado antes de migrar. Drizzle Kit es preciso en la mayoría de cambios, pero comprueba siempre operaciones destructivas (drops, renames).

pnpm db:migrate

Aplica las migraciones pendientes a la base conectada vía DATABASE_URL.

When to use

• Tras pnpm db:generate — para aplicar tu nueva migración
• Tras hacer pull de git cuando un compañero (o upstream) añadió migraciones
• En una base fresca — para crear todas las tablas desde cero
• Durante el setup local — justo después de clonar (consulta Installation)

When not to use

• Cuando cambiaste el esquema pero aún no has ejecutado db:generate — genera primero
• Para inspeccionar datos — usa db:studio

What it does

1. Se conecta a Postgres usando DATABASE_URL
2. Ejecuta cualquier SQL de migración aún no registrado en el journal de migraciones de la base
3. Actualiza el journal para que la misma migración no se aplique dos veces

Example

pnpm db:migrate

Ejecuta esto tras cada flujo de cambio de esquema:

pnpm db:generate && pnpm db:migrate

En CI o deploy de producción, ejecuta pnpm db:migrate como parte del paso de release (cuando las env vars ya estén disponibles).

Troubleshooting

pnpm db:studio

Abre Drizzle Studio — una UI web local para explorar tablas, ver filas y ejecutar consultas ad-hoc.

When to use

• Inspeccionar datos durante el desarrollo (users, links, files, sessions)
• Depurar si una migración creó las columnas esperadas
• Verificar que los sign-ups de prueba escribieron las filas correctas
• Explorar tablas desconocidas tras hacer pull de migraciones nuevas

When not to use

• Para cambiar el esquema — edita los archivos TypeScript del esquema y ejecuta db:generate + db:migrate
• En producción como herramienta de admin principal — usa el Supabase Dashboard o un admin dedicado para datos de producción
• Como sustituto de scripts de seed adecuados — Studio es para inspección, no para setup repetible

What it does

Inicia un servidor local (Drizzle Kit imprime la URL, normalmente https://local.drizzle.studio). Se conecta usando DATABASE_URL de .env.

Example

pnpm db:studio

Mantén la terminal abierta mientras usas Studio. Detén con Ctrl+C cuando termines.

Typical workflows

First-time local setup

cp .env.example .env
# fill in DATABASE_URL
pnpm db:migrate
pnpm dev

No hace falta db:generate — las migraciones ya vienen en el repo.

You changed the schema

# 1. Edit src/lib/db/schema/*.ts and export from schema.ts
pnpm db:generate
pnpm db:migrate
pnpm db:studio   # optional — verify the new table

You pulled new migrations from git

pnpm db:migrate

You want to inspect data without changing anything

pnpm db:studio

Migration files in the repo

Las migraciones aplicadas viven en drizzle/migrations/. Cada carpeta contiene:

• migration.sql — SQL ejecutado por db:migrate
• snapshot.json — snapshot interno del esquema para el próximo diff de db:generate

Haz commit de los archivos de migración en git. Compañeros y deploys de producción dependen del mismo historial SQL ordenado.

No edites a mano migraciones ya aplicadas en producción. Si necesitas corregir un error antes de que alguien haya migrado, borra la carpeta de migración no aplicada y regenera. Si ya se aplicó, crea una migración correctiva nueva.

Next steps

Adding a New Table — Tutorial completo: esquema → export → generate → migrate → queries.

Database — Resumen de arquitectura, convenciones de esquema y patrones de consulta.