Development

Migraciones en CodeIgniter 4: la guía que faltaba

Corte isométrico de un plano de ingeniería con niveles cilíndricos de base de datos de azul cobalto y vidrio esmerilado dentro de un marco de aluminio cepillado con rieles de cobre y engranajes de latón sobre una cuadrícula de dibujo clara

🚀 La guía completa que olvidaron escribir

¿Está dando el salto de CodeIgniter 3 a 4? ¡No es el único! Como a muchos desarrolladores, me atrajo la estructura moderna y organizada de CodeIgniter 4. Pero con las migraciones (migrations) de bases de datos, pronto me encontré con un muro: la documentación oficial es escasa y los recursos de la comunidad suelen estar desactualizados o ser confusos.

Como antes apenas había experimentado con migraciones en Ruby, siempre me las saltaba en CodeIgniter 3. Pero con CI4 supe que era hora de profundizar, sobre todo porque unas migraciones sólidas son esenciales para hacer pruebas confiables y llevar el control de versiones de la base de datos en cualquier proyecto serio.

El desafío: ¿cómo espera CodeIgniter 4 que sea su tabla de migraciones?

Suena sencillo, pero la documentación simplemente… no está. Después de horas de juntar publicaciones de foros, incidencias de GitHub y código fuente, finalmente resolví el rompecabezas.

Ideas principales

Esta guía busca ahorrarle ese mismo dolor de cabeza:

  • Cómo configurar y usar las migraciones de CodeIgniter 4

  • Cómo debe ser realmente el esquema de la tabla de migraciones

  • Consejos profesionales para administrar sin contratiempos las bases de datos de sus proyectos CI4

Si se ha quedado atascado, se ha frustrado o simplemente quiere una respuesta sin rodeos sobre las migraciones de CodeIgniter 4, está en el lugar correcto.

Esquema de la tabla de migraciones de CodeIgniter 4+ (MySQL/MariaDB)

SET NAMES utf8mb4;   SET FOREIGN_KEY_CHECKS = 0;

— Estructura de la tabla de migraciones

DROP TABLE IF EXISTS migrations;
CREATE TABLE migrations (

id int(11) NOT NULL AUTO_INCREMENT,

name varchar(255) DEFAULT NULL,

version varchar(255) DEFAULT NULL,

`group` varchar(255) DEFAULT NULL,

batch int(11) DEFAULT NULL,

class varchar(255) DEFAULT NULL,

namespace varchar(255) DEFAULT NULL,

time int(11) DEFAULT NULL,

PRIMARY KEY (id)

) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;

Encontrará más detalles y la migración completa en GitHub.

Las versiones recientes de CodeIgniter 4 crean la tabla de migraciones por usted la primera vez que ejecuta php spark migrate. Crearla a mano sigue siendo útil cuando su usuario de base de datos no tiene permiso para crear tablas o cuando un administrador de bases de datos ejecuta cada cambio de esquema.

Si elige la vía manual, hay dos cosas que debe saber. Primero, group es una palabra reservada en MySQL y MariaDB, así que necesita comillas invertidas, como arriba, o CREATE TABLE fallará con un error de sintaxis. Segundo, la tabla que el framework crea para sí mismo es más estricta que esta: en el código fuente actual, id es un BIGINT sin signo, las columnas version, class, group, namespace, time y batch son todas NOT NULL, y no hay columna name. CodeIgniter ignora name, así que no causa problemas. La tabla siempre reside en su grupo de base de datos predeterminado, incluso cuando una migración apunta a otro.

Antes de ejecutar nada: conecte CI4 a una base de datos

Spark lee la conexión desde su archivo .env. Un proyecto nuevo incluye una plantilla llamada env; cópiela a .env y complete las líneas database.default.*:

database.default.hostname = localhost
database.default.database = ci4
database.default.username = ci4_user
database.default.password = change-me
database.default.DBDriver = MySQLi
database.default.port = 3306

Su primera migración, paso a paso

1. Genere el archivo

php spark make:migration AddUsersTable

Esto crea un archivo en app/Database/Migrations/ cuyo nombre empieza con una marca de tiempo, como 2026-11-13-190000_AddUsersTable.php. La marca de tiempo determina el orden de ejecución de las migraciones, así que nunca la cambie a mano.

2. Describa el cambio

Cada migración tiene un up() que aplica el cambio y un down() que lo deshace:

<?php

namespace App\Database\Migrations;

use CodeIgniter\Database\Migration;

class AddUsersTable extends Migration
{
    public function up()
    {
        $this->forge->addField([
            'id'        => ['type' => 'INT', 'constraint' => 11, 'unsigned' => true, 'auto_increment' => true],
            'firstname' => ['type' => 'VARCHAR', 'constraint' => 100],
            'lastname'  => ['type' => 'VARCHAR', 'constraint' => 100],
            'email'     => ['type' => 'VARCHAR', 'constraint' => 255],
        ]);
        $this->forge->addKey('id', true);
        $this->forge->createTable('users');
    }

    public function down()
    {
        $this->forge->dropTable('users');
    }
}

3. Ejecútela, revísela y deshágala

Comando Qué hace
php spark migrate Ejecuta todas las migraciones que aún no se han ejecutado
php spark migrate:status Enumera cada migración e indica si se ha ejecutado
php spark migrate:rollback Deshace el último lote mediante cada down()
php spark migrate:refresh Revierte todo y después vuelve a ejecutarlo

La configuración, como el nombre de la tabla, se encuentra en app/Config/Migrations.php.

Qué es un «lote» y por qué importa al revertir

Cada vez que ejecuta php spark migrate, todos los archivos que se aplican en esa ejecución comparten un número de lote en la tabla de migraciones. Los tres archivos nuevos del lunes son el lote 1; los dos del miércoles, el lote 2. Un simple migrate:rollback deshace solo el lote 2, empezando por el archivo más reciente.

Las opciones que conviene memorizar:

  • php spark migrate -n Acme\Blog ejecuta migraciones de otro espacio de nombres, como un módulo. El espacio de nombres predeterminado es App.
  • php spark migrate --all ejecuta las migraciones de todos los espacios de nombres que conoce CodeIgniter.
  • php spark migrate:rollback -b 1 revierte hasta dejar solo el lote 1. -b 0 lo devuelve a un esquema vacío.
  • -f al revertir o reiniciar omite la pregunta «Are you sure?», que CodeIgniter solo hace en producción.

migrate:status muestra el espacio de nombres, la versión, el nombre de archivo, el grupo, la fecha en que se ejecutó cada archivo y su lote. Un guion en la columna «Migrated On» significa que no se ha ejecutado.

migrate:refresh elimina todo y lo reconstruye, lo que también borra sus datos. Es excelente en su computadora portátil; en producción, puede marcar un antes y un después en su carrera.

Un ejemplo completo: usuarios y sus publicaciones

Esta segunda migración depende de la primera e incluye una clave foránea y marcas de tiempo. Genérela con php spark make:migration AddPostsTable:

<?php

namespace App\Database\Migrations;

use CodeIgniter\Database\Migration;

class AddPostsTable extends Migration
{
    public function up()
    {
        $this->forge->addField([
            'id'         => ['type' => 'INT', 'constraint' => 11, 'unsigned' => true, 'auto_increment' => true],
            'user_id'    => ['type' => 'INT', 'constraint' => 11, 'unsigned' => true],
            'title'      => ['type' => 'VARCHAR', 'constraint' => 200],
            'body'       => ['type' => 'TEXT', 'null' => true],
            'created_at' => ['type' => 'DATETIME', 'null' => true],
            'updated_at' => ['type' => 'DATETIME', 'null' => true],
        ]);
        $this->forge->addKey('id', true);
        $this->forge->addKey('user_id');
        $this->forge->addForeignKey('user_id', 'users', 'id', 'CASCADE', 'CASCADE');
        $this->forge->createTable('posts');
    }

    public function down()
    {
        $this->forge->dropTable('posts', true);
    }
}

Observe que user_id es un INT sin signo, exactamente igual que users.id. MySQL exige que las dos columnas de una clave foránea tengan el mismo tamaño de entero y signo, y una diferencia es la causa más común de que una migración falle a mitad del proceso. addForeignKey() recibe la columna, la tabla padre, la columna padre y, después, las acciones de actualización y eliminación.

Como el archivo de publicaciones tiene una marca de tiempo posterior a la del archivo de usuarios, php spark migrate siempre crea users primero. Al revertir, el orden se invierte, por lo que se elimina posts antes que la tabla a la que apunta.

Llene las tablas: semillas

Las migraciones construyen la estructura; las semillas (seeders) la llenan de datos:

php spark make:seeder UserSeeder
php spark db:seed UserSeeder

El archivo generado queda en app/Database/Seeds/. Complete run():

<?php

namespace App\Database\Seeds;

use CodeIgniter\Database\Seeder;

class UserSeeder extends Seeder
{
    public function run()
    {
        $this->db->table('users')->insertBatch([
            ['firstname' => 'Ada', 'lastname' => 'Lovelace', 'email' => '[email protected]'],
            ['firstname' => 'Alan', 'lastname' => 'Turing', 'email' => '[email protected]'],
        ]);
    }
}

Para más de una tabla, cree un DatabaseSeeder cuyo run() llame a los demás en orden, con $this->call('UserSeeder'); seguido de $this->call('PostSeeder');. Después, php spark db:seed DatabaseSeeder llena todo, primero los padres y luego los hijos, para que las claves foráneas no protesten. migrate no ejecuta las semillas por sí solo; la carga de datos siempre requiere un comando separado.

Las semillas no se registran en ninguna parte, así que ejecutar una dos veces inserta las filas dos veces. Para empezar de cero en una base de datos de desarrollo, ejecute migrate:refresh y después db:seed.

Errores comunes y qué significan

  • «Unable to connect to the database.» Spark no puede conectarse al servidor. Revise que exista el archivo .env (no solo env), que las líneas no estén comentadas y que el host y el puerto sean correctos.
  • «There is a gap in the migration sequence near version number...» aparece cuando CodeIgniter intenta revertir una migración registrada en la tabla que ya no existe en el disco. Normalmente alguien eliminó o cambió el nombre de un archivo que ya se había ejecutado. Restáurelo.
  • «The migration class ... could not be found.» El nombre de la clase o el espacio de nombres dentro del archivo no coincide con lo que espera CodeIgniter. El nombre de la clase debe coincidir con la parte del nombre de archivo posterior a la marca de tiempo, y el espacio de nombres debe ser App\Database\Migrations, a menos que ejecute desde un módulo.
  • El error 1005 con errno 150 proviene de MySQL, no de CodeIgniter: la clave foránea está mal formada. Nueve de cada diez veces las dos columnas difieren en tamaño o en unsigned.

Tres hábitos que evitan sufrimientos

  • Nunca edite una migración que ya se haya ejecutado en la base de datos de otra persona. Escriba una nueva que modifique la tabla.
  • Siempre escriba down(), aunque crea que nunca va a revertir. Lo hará.
  • Un cambio por migración. Un archivo pequeño es fácil de revertir; uno gigante, no.

¿Necesita filas para llenar sus tablas nuevas? El generador de contactos y direcciones exporta usuarios de prueba realistas como inserciones SQL, y el generador de perfiles ficticios crea una identidad inventada completa cuando necesita llenar más columnas.

Fuentes

J

J. Walker

Especialista en tecnología, desarrollador y autor. Comparte ideas sobre herramientas de código abierto, automatización y arquitectura de sistemas modernos.

← Artículo anterior Generador de contactos y direcciones con códigos postales Artículo siguiente → Presupuesto federal de EE. UU. como familiar: cifras de 2026