Saltar al contenido principal

Migraciones de Base de Datos

Fyso usa Drizzle ORM para gestionar migraciones de base de datos.

Estructura de Migraciones​

Las migraciones están en /packages/db/migrations/ y son generadas por Drizzle Kit a partir de los schemas TypeScript.

Esquemas en /packages/db/src/schema/​

  • public.ts - Tablas globales (tenants, admins, sessions, api_keys)
  • tenant.ts - Tablas específicas de cada tenant (entities, fields, records, business_rules)

Cómo funciona​

  1. Defines o modificas schemas en TypeScript
  2. Ejecutas bun run generate para generar migraciones SQL
  3. Drizzle crea archivos .sql en /migrations/
  4. Ejecutas bun run migrate para aplicarlas

Problema: Columna faltante en tenants existentes​

Síntoma​

Error: column "published_version" of relation "business_rules" does not exist

Causa​

El tenant fue creado antes de que existiera la migración que agrega la tabla business_rules o sus columnas.

Solución con Drizzle​

Opción 1: Script de migración automático (Recomendado)​

Aplicar todas las migraciones de Drizzle a todos los tenants:

cd packages/db
bun run migrate:tenants

Aplicar solo a un tenant específico:

cd packages/db
bun run migrate:tenants --tenant=demo

Este script:

  1. Lee las migraciones de Drizzle desde /packages/db/migrations/
  2. Conecta a cada tenant schema (tenant_xxx)
  3. Aplica las migraciones pendientes usando drizzle-orm/migrator
  4. Maneja errores y migraciones ya aplicadas automáticamente

Opción 2: Migración manual con Drizzle​

# Desde packages/db
cd packages/db

# Regenerar migraciones desde schemas (si hiciste cambios)
bun run generate

# Aplicar migraciones al schema public
bun run migrate

# Aplicar a un tenant específico (necesitarás modificar migrate.ts)

Nuevos Tenants​

Los nuevos tenants creados después de implementar las migraciones ya incluirán todas las columnas. El sistema aplica automáticamente todas las migraciones disponibles al momento de la creación.

Verificación​

Para verificar que un tenant tiene todas las migraciones:

-- Ver estructura de business_rules
\d tenant_demo.business_rules

-- Debería mostrar:
-- - published_version | integer
-- - published_at | timestamp with time zone
-- - published_by | uuid

Desarrollo: Crear Nueva Migración​

1. Modificar el Schema TypeScript​

Edita los archivos en /packages/db/src/schema/:

// packages/db/src/schema/tenant.ts
export const notifications = pgTable('notifications', {
  id: uuid('id').defaultRandom().primaryKey(),
  userId: uuid('user_id').references(() => users.id),
  message: text('message').notNull(),
  read: boolean('read').default(false),
  createdAt: timestamp('created_at').defaultNow(),
});

2. Generar Migración con Drizzle​

cd packages/db
bun run generate

Esto crea un archivo en /migrations/ con el SQL necesario.

3. Aplicar a Schema Public (si aplica)​

bun run migrate

4. Aplicar a Tenants Existentes​

cd packages/db
bun run migrate:tenants

5. Commits y Deploy​

git add packages/db/migrations/
git commit -m "feat: add notifications table"

En producción, el script de deploy debe ejecutar:

cd packages/db
bun run migrate           # Para schema public
bun run migrate:tenants   # Para tenants

Troubleshooting​

Error: "relation does not exist"​

  • Ejecutar: bun run scripts/migrate-tenants.ts --tenant=NOMBRE

Error: "already exists"​

  • La migración ya está aplicada (esto es normal)
  • El script lo detecta y lo marca como "skipped"

Error: "permission denied"​

  • Verificar que el usuario de la DB tenga permisos en el schema del tenant
  • Verificar las credenciales en .env
Creado con Fyso