Saltar a contenido

🧱 Migraciones y carga de datos

CORDIA utiliza migraciones de Laravel para definir y versionar la estructura de la base de datos, y seeders para cargar datos iniciales necesarios para el funcionamiento del sistema.

⚙️ Migraciones

Las migraciones definen las tablas, relaciones y restricciones de la base de datos.

Recomendado (script de conveniencia):

# Ejecutar migraciones en el entorno por defecto (dev)
./scripts/migrate.sh --env=dev

# Fresh (recrear) + seed
./scripts/migrate.sh --env=dev --fresh --seed

# Solo seed en otro entorno
./scripts/migrate.sh --env=test --seed

Alternativa (Artisan dentro del contenedor):

# Ejecutar todas las migraciones
docker compose exec apilaravel php artisan migrate

# Revertir la última migración
docker compose exec apilaravel php artisan migrate:rollback

# Refrescar todas las migraciones (elimina y vuelve a crear)
docker compose exec apilaravel php artisan migrate:refresh

Las migraciones están en database/migrations. Pueden ser personalizadas o generadas automáticamente.

🌱 Seeders

Los seeders permiten insertar datos iniciales como países, tipos de fuentes, campos léxicos, etc.

# Ejecutar todos los seeders
docker compose exec apilaravel php artisan db:seed

# Ejecutar un seeder específico
docker compose exec apilaravel php artisan db:seed --class=NombreDelSeeder

Los seeders están organizados por bloques y todos usan una clase base común llamada BaseMultilingualImporter, incluso aquellos que no requieren traducciones.

Puedes consultar el archivo DatabaseSeeder.php para ver el orden de ejecución.

🧪 Datos de prueba

Si necesitas poblar el sistema con datos ficticios para pruebas:

# Usa un seeder específico con datos simulados
docker compose exec apilaravel php artisan db:seed --class=SeederDePrueba

No ejecutar estos seeders en entornos de producción.

✅ Buenas prácticas

  • Agrupar migraciones por tipo de recurso.
  • Mantener consistencia en nombres y convenciones.
  • No modificar migraciones ya ejecutadas en producción.
  • Documentar los cambios estructurales relevantes.

Consulta la documentación de base de datos para entender las relaciones y dependencias entre tablas.

📄 Detalle: Importadores y Seeders (revisión 1)

Este documento describe el pipeline de importación y seed inicial de CORDIA, basado en los seeders masivos y las clases Importer.

Componentes

  • Seeder orquestador: app/api-laravel/database/seeders/MassiveDataSeeder.php
  • Seeders base: ejecutados desde DatabaseSeeder (migrate:fresh --seed)
  • Importers: clases en app/api-laravel/app/Imports/ que insertan datos en tablas y, cuando existen, sus traducciones
  • Script de conveniencia: scripts/data-imports-run.sh

Flujo de MassiveDataSeeder

MassiveDataSeeder lee archivos de database/seeders/data/${SEED_ENV} y, para cada archivo que cumple el patrón, invoca el Importer correspondiente:

  • Patrón de archivos: ^(?!NO-)(.+TableSeeder)\.(\d+)\.(env)\.(json|csv)$
  • Ej.: LanguagesTableSeeder.010.dev.json, EntryTableSeeder.200.dev.csv
  • Resolución de Importer: \App\Imports\{Nombre}Importer donde {Nombre} = parte antes de TableSeeder en StudlyCase
  • Formatos soportados: json, csv (CSV con cabecera)
  • Variable de entorno: SEED_ENV (por defecto dev)

Código relevante: app/api-laravel/database/seeders/MassiveDataSeeder.php.

BaseMultilingualImporter

Muchos importers heredan de BaseMultilingualImporter (app/api-laravel/app/Imports/BaseMultilingualImporter.php). Proporciona:

  • Inserción idempotente con updateOrInsert sobre la tabla principal
  • Soporte opcional de traducciones si existe la tabla *_translations
  • Hooks opcionales: beforeImport(), afterInsert($item, $id)
  • Responsabilidades del Importer hijo:
  • mainTable(), translationTable(), keyField()
  • buildMainData($item) y buildTranslationData($trans, $locale, $id)

Ejecución

  • Reseteo y seed completo (recomendado): 
    ./scripts/migrate.sh --env=dev --fresh --seed
  • Alternativa (Artisan): 
    docker compose exec apilaravel php artisan migrate:fresh --seed
  • Con entorno específico (usado por el seeder): 
    docker compose exec -e SEED_ENV=dev apilaravel php artisan migrate:fresh --seed
  • Script de utilidad (resetea BD, corre seeders y ejecuta parsers registrados si se indican): 
    ./scripts/data-imports-run.sh --env=dev --import=etymos.txt
    El script buscará un comando Artisan llamado cordia:parse-<nombre>-<ext> para cada archivo indicado (ver sección siguiente).

Convención de comandos de parsing

Para ejecutar importaciones específicas post-seed, el script data-imports-run.sh construye nombres de comando del tipo:

  • cordia:parse-{name}-{extension}

Ejemplo: para etymos.txt intenta cordia:parse-etymos-txt (en nuestro caso el comando disponible es cordia:parse-etymos_della-txt).

Buenas prácticas

  • Nombrar archivos de seed con orden (.NNN.), entorno (.dev|test|pre|prod.) y formato
  • Evitar duplicados: confiar en claves primarias y updateOrInsert
  • Idempotencia: los importers no deben fallar si se ejecutan varias veces
  • Aislar traducciones: cuando existan tablas *_translations, respetar el mismo keyField