Migraciones de base

Los cambios de schema del core y de los módulos se aplican con migraciones versionadas. No se editan a mano en cada base ni se distribuyen como scripts SQL sueltos: se escriben una vez, quedan versionadas en el repositorio del módulo y se aplican en todas las bases con el mismo comando.

Módulos y ubicaciones

Cada conjunto de migraciones pertenece a un módulo, y el motor los descubre solo:

Módulo	Directorio de migraciones
`core`	`admin/migrations/`
`erp`	`modules/erp-migrations/`
Cualquier otro	`modules/{módulo}/migrations/`

Formato de una migración

El nombre del archivo es una marca de tiempo de 14 dígitos, un guion bajo y el nombre en snake_case: 20260611103000_add_realm_to_profiles.php. También se aceptan archivos .sql con el mismo patrón.

Una migración PHP extiende AbstractMigration y define up() y down():

<?php

use Histrix\Migration\AbstractMigration;

class AddRealmToProfiles extends AbstractMigration
{
    public function up()
    {
        $this->addColumn('HTXPROFILES', 'realm', "VARCHAR(255) NOT NULL DEFAULT 'web'");
    }

    public function down()
    {
        $this->dropColumn('HTXPROFILES', 'realm');
    }
}

AbstractMigration provee ayudas idempotentes para no romper en bases donde el cambio ya existe:

Método	Uso
`execute($sql)`	Ejecuta SQL literal
`query($sql)`	Ejecuta y devuelve el resultado
`tableExists($tabla)`	Verifica la existencia de una tabla
`columnExists($tabla, $columna)`	Verifica la existencia de una columna
`createTable($nombre, $columnas, $opciones)`	`CREATE TABLE IF NOT EXISTS` (InnoDB y utf8mb4 por defecto)
`dropTable($nombre)`	Elimina la tabla
`addColumn($tabla, $columna, $tipo, $after)`	Agrega la columna solo si falta
`dropColumn($tabla, $columna)`	Elimina la columna
`renameColumn($tabla, $viejo, $nuevo, $tipo)`	Renombra la columna
`addIndex($tabla, $columnas, $nombre, $unique)`	Crea un índice
`dropIndex($tabla, $nombre)`	Elimina un índice

Comandos

Todos aceptan --db={base} para una base puntual o --all-databases para recorrer todas las declaradas en config.xml, y --module={módulo} para limitar el alcance.

# Estado de las migraciones
php histrix migrate:status --all-databases

# Aplicar las pendientes (--dry-run muestra sin ejecutar)
php histrix migrate --all-databases
php histrix migrate --db=cliente --module=erp-full --dry-run

# Revertir el último lote (o N lotes con --steps)
php histrix migrate:rollback --db=cliente
php histrix migrate:rollback --db=cliente --steps=3

# Crear una migración vacía
php histrix migrate:generate --module=erp-full "add realm to profiles"

# Comparar el schema real contra el SQL del módulo
php histrix migrate:diff --db=cliente --module=erp-full
php histrix migrate:diff --db=cliente --module=erp-full --generate

# Exportar al módulo las tablas y rutinas que existen en la base pero no en su SQL
php histrix migrate:export --module=erp-full --dry-run

Opciones específicas:

Comando	Opción	Efecto
`migrate`	`--dry-run`	Muestra lo que haría sin tocar la base
`migrate:rollback`	`--steps=N`	Cantidad de lotes a revertir (1 por defecto)
`migrate:diff`	`--generate`	Genera una migración con las diferencias encontradas
`migrate:diff`	`--force`	Continúa ante diferencias que normalmente abortan
`migrate:generate`	`--baseline`	Genera la migración base a partir del schema existente
`migrate:generate`	`--mark-executed`	Marca la baseline como ya aplicada

Registro de ejecución

Cada base lleva su propia tabla HTX_MIGRATIONS con la versión, el módulo, el nombre, el lote (batch) y las marcas de inicio y fin. El rollback usa el lote para saber qué revertir en conjunto.

Panel web

El panel de migraciones está en admin/migrations/index.php. Es un PHP independiente, no un XML de Histrix: permite ver el estado, aplicar pendientes, revertir y crear migraciones desde el navegador.