Download the PHP package mongoose-studio/phobos-framework-database-migrations without Composer

Phobos Framework - Database Migrations

Migraciones y seeders para Phobos Framework Database Layer, con un DSL agnóstico de motor llamado Harmonia que compila a MySQL, PostgreSQL y SQLite desde una única definición. Se para sobre mongoose-studio/phobos-framework-database.

Coherente con la filosofía database-first de Phobos: la base de datos es la fuente de la verdad. Las migraciones versionan el esquema de forma explícita, y el Introspector hace el camino inverso — reconstruye la definición leyendo el catálogo de una base viva. Como Harmonia es una representación intermedia universal, un esquema se traduce entre motores: DB ⇄ Harmonia ⇄ SQL (cualquier motor).

Características

• 🎯 DSL agnóstico - Un Blueprint fluido compila a MySQL, PostgreSQL y SQLite
• 🧬 Convenciones Phobos - uuidv7() (calza con keyStrategy = uuidv7) y auditColumns() en una línea
• 🔀 Escotilla híbrida - rawType() y Schema::raw() para lo específico de un motor
• 📦 Harmonia - El DSL serializa a JSON versionado y portable, con modo estricto anti-inyección
• 🔎 Introspección - DB → Harmonia: reconstruye definiciones desde una base viva y migra entre motores
• 🔬 Diff de esquemas - Compara dos bases del mismo motor (dev↔prod, tenant↔golden) y exporta el delta a Harmonia/SQL/migración
• 🌱 Seeders idempotentes - insertOrIgnore / upsert traducidos por motor
• 🧾 Dry-run / SQL plano - Exporta el DDL sin ejecutar nada, incluso 100% offline
• 🗂️ Multi-tenant - El Migrator recibe la conexión; aplicar a N tenants es recorrer conexiones
• 🧮 Tabla de control - phobos_migrations con batch (rollback por lote) y checksum (detecta drift)

Instalación

Dependencias

Este paquete requiere:

• mongoose-studio/phobos-framework-database ^3.2 (capa de base de datos)
• El/los driver(s) que uses: -mysql, -postgres y/o -sqlite
• PHP 8.4+ y la extensión ext-pdo

Una migración

Cada archivo retorna una clase anónima que extiende Migration (sin colisión de nombres, calza con el prefijo de timestamp del archivo):

Portabilidad agnóstica (mapeo por motor)

Escotilla híbrida para lo específico de un motor:

Harmonia — el DSL como formato JSON portable

El Blueprint es un modelo de datos separado de la compilación, así que la definición se serializa e importa en el formato Harmonia (JSON con marca de versión). Una definición → SQL de cualquier motor.

Modo estricto (import de fuentes no confiables)

Schema::fromJson() y Harmonia::decode() son estrictos por defecto: rechazan la escotilla rawType, tipos/comandos fuera de la whitelist e identificadores que no sean nombres simples — cerrando la vía de inyección de SQL. Para tu propio round-trip con rawType, usa strict: false explícito:

Aviso de seguridad: un archivo de migración PHP es código de confianza y ejecuta cualquier SQL (Schema::raw, db()->execute). La defensa es de proceso (PR + branch protegida

• rol DB de least-privilege). Para aceptar definiciones de terceros, usa Harmonia en modo estricto (declarativo, sin código arbitrario).

Seeders idempotentes (sin duplicar)

• Reference data de una sola vez → escríbelo como migración (corre una vez, tracked).
• Catálogos re-sembrables / dev → helpers idempotentes:

insertOrIgnore / upsert se traducen a INSERT IGNORE / ON CONFLICT / ON DUPLICATE KEY según el motor.

CLI

Crea un phobos-migrations.php en la raíz que registre las conexiones (dbConfig) y retorne las rutas:

Introspección — DB → Harmonia (el inverso)

Coherente con database-first: la DB es la fuente de la verdad. El Introspector lee el catálogo y reconstruye la definición.

Como Harmonia es el IR universal, recompilas a otro motor (migrar un esquema de un motor a otro):

CLI:

Fidelidad best-effort: PostgreSQL recupera la mayor riqueza (uuid, jsonb→json, boolean, timestamptz, bigserial→bigIncrements). SQLite es lossy por su afinidad de tipos (uuid/json/boolean ≈ text/integer) salvo que se hayan declarado con esos nombres. Los defaults se preservan verbatim (rawDefault, no portable) excepto los booleanos, que se normalizan a true/false.

Diff de esquemas (same-engine)

Compara dos esquemas completos del mismo motor y produce el delta estructural: tablas agregadas/eliminadas y, por cada tabla común, columnas +/-/~, índices, uniques, FKs y PK. Reusa el Introspector (DB→Blueprint), así que el delta se exporta a Harmonia, a SQL o a un archivo de migración.

Same-engine a propósito. El diff cross-engine (con equivalencia de tipos char(36)≈uuid, tinyint(1)≈boolean, …) es ambiguo y quiere resolución visual con un humano en el loop → se reserva para Deimos Studio. Si las dos fotos declaran motores distintos, el diff se rechaza.

Subconjunto aplicable. El export cubre lo que el ALTER del DSL sabe compilar: crear tablas, agregar columnas/índices/FKs y eliminar columnas. Lo demás —modificar columnas, uniques nuevas, cambios de PK y lo destructivo (drops)— se reporta en notes() para revisión manual, no se aplica solo.

Multi-tenant

El Migrator recibe el nombre de conexión, así que aplicar a N bases de tenant es recorrer sus conexiones:

Tabla de control

phobos_migrations: version (timestamp), batch (para rollback por lote), checksum (detecta drift si editas una migración ya aplicada), applied_at.

Notas por motor

• PostgreSQL / SQLite: DDL transaccional — una migración fallida revierte por completo.
• MySQL: el DDL hace commit implícito; una migración a medias puede dejar estado parcial (parte cada cambio grande en migraciones pequeñas).
• SQLite: ALTER es limitado (agregar/eliminar columna sí; modificar columna requiere reconstruir la tabla — roadmap).

Tests

Suite PHPUnit (^11) — la lógica pura corre sin base de datos; el resto sobre SQLite :memory:.

El tests/bootstrap.php también funciona sin composer (autoloader manual de los paquetes hermanos del monorepo), así que se puede correr con un phpunit.phar directo. Cubre: DSL/Blueprint, Harmonia (incluida la seguridad del modo estricto), las 3 gramáticas, el Migrator (run/rollback/status/pretend/drift), la introspección, el diff de esquemas y los seeders idempotentes. El src/ completo pasa PHPStan nivel 8 sin errores.

Compatibilidad

• MySQL/MariaDB, PostgreSQL 12+, SQLite 3
• PHP 8.4+

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor

Marcel Rojas
[email protected]
Mongoose Studio

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Phobos Framework by Mongoose Studio