Migraciones de base de datos

¿Qué son las migraciones?

Las migraciones son como un sistema de control de versiones para la base de datos. Permiten que un equipo comparta y gestione la definición del esquema de la aplicación. Seguramente hayas vivido la situación de tener que decir a otro miembro del equipo: “Añade manualmente esta columna a tu base de datos local tras hacer pull”. Las migraciones resuelven ese problema. Los archivos de migración se guardan en el directorio database/migrations. Cada nombre de archivo incluye una marca de tiempo que Laravel usa para determinar el orden de ejecución.

Creación de un archivo de migración

Crea un nuevo archivo de migración con el comando Artisan make:migration.

php artisan make:migration create_posts_table

A partir del nombre, Laravel deduce el nombre de la tabla y genera el stub adecuado. Con create_posts_table te crea de partida el código para crear la tabla posts.

Estructura de una migración

Una clase de migración tiene dos métodos: up y down.

up: añade tablas, columnas o índices a la base de datos.
down: revierte lo que hace up. Se llama al hacer rollback.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Ejecuta la migración
     */
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamps();
        });
    }

    /**
     * Revierte la migración
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Principales métodos para definir columnas

La clase Blueprint ofrece muchos tipos de columna.

Método	Descripción
`$table->id()`	Clave primaria auto-incremental (alias de `bigIncrements('id')`)
`$table->string('name')`	Columna equivalente a VARCHAR (255 por defecto)
`$table->text('body')`	Columna TEXT
`$table->integer('count')`	Columna INTEGER
`$table->boolean('active')`	Guarda booleano como TINYINT
`$table->timestamp('published_at')`	Columna TIMESTAMP
`$table->timestamps()`	Añade `created_at` y `updated_at` juntos
`$table->softDeletes()`	Añade la columna `deleted_at` para soft delete
`$table->foreignId('user_id')`	Columna `BIGINT UNSIGNED` para clave foránea

Modificadores de columna

Puedes encadenar modificadores en la definición de la columna.

$table->string('email')->unique();
$table->string('name')->nullable();
$table->integer('votes')->default(0);
$table->string('title')->after('id'); // Se coloca después de la columna indicada

Columnas e índices vectoriales

El método vector crea una columna vector para almacenar vectores de embedding. Indica en dimensions la dimensión de salida del proveedor de embeddings que utilices.

$table->vector('embedding', dimensions: 1536);

Las columnas vectoriales están disponibles en conexiones PostgreSQL que utilicen la extensión pgvector y en MariaDB 11.7 o superior. En PostgreSQL, habilita pgvector antes de crear una columna vectorial.

Schema::ensureVectorExtensionExists();

Para acelerar las búsquedas por similitud vectorial, añade un index a la columna vector. Este índice usa la distancia coseno.

$table->vector('embedding', dimensions: 1536)->index();

Para eliminar un índice vectorial existente, usa dropVectorIndex.

$table->dropVectorIndex('documents_embedding_vectorindex');

Creación de índices en línea

Al crear un índice sobre una tabla grande, normalmente la tabla queda bloqueada mientras se construye el índice y las lecturas y escrituras deben esperar. En MySQL, si añades el modificador inplace a la definición de un índice o una clave foránea, la operación se ejecuta con el algoritmo INPLACE.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace();
    $table->foreign('team_id')
        ->references('id')
        ->on('teams')
        ->inplace();
});

Combina inplace con el modificador lock para controlar el bloqueo de tabla durante la operación. Con none, las lecturas y escrituras siguen disponibles en las operaciones que MySQL lo permita.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace()->lock('none');
});

Esta funcionalidad es exclusiva de MySQL. Consulta la documentación de operaciones DDL online de MySQL para confirmar que la operación que ejecutas soporta el algoritmo INPLACE y el modo de bloqueo indicado. Para usar inplace en operaciones de clave foránea, desactiva antes las comprobaciones de claves foráneas.

Ejecución de migraciones

Con migrate ejecutas todas las migraciones pendientes.

php artisan migrate

Para ver el estado de las ejecutadas y pendientes, usa migrate:status.

php artisan migrate:status

En producción, al ejecutar migraciones aparece un prompt de confirmación. Para ejecutarlo sin confirmación usa --force, pero ten precaución porque algunas operaciones destruyen datos.

Rollback

Para deshacer el último lote de migraciones, usa migrate:rollback.

php artisan migrate:rollback

Para revertir un número concreto de pasos, usa la opción --step.

# Revertir las 5 migraciones más recientes
php artisan migrate:rollback --step=5

Para revertir todas las migraciones y volver a ejecutarlas, usa migrate:refresh.

php artisan migrate:refresh

migrate:refresh recrea todas las tablas, así que los datos existentes se pierden. Es útil para reiniciar la base de datos durante el desarrollo.

Ejemplo práctico: crear la tabla posts

Repasemos el flujo completo con una tabla posts para gestionar publicaciones de blog.

1. Generar el archivo de migración

php artisan make:migration create_posts_table

2. Editar la migración

Abre y edita database/migrations/xxxx_xx_xx_xxxxxx_create_posts_table.php.

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamp('published_at')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

3. Ejecutar la migración

php artisan migrate

Después de ejecutarla, la tabla posts se creará en la base de datos.

4. Añadir columnas más tarde

Para añadir nuevas columnas a una tabla existente, no edites la migración original: crea una nueva.

php artisan make:migration add_excerpt_to_posts_table

public function up(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->string('excerpt')->nullable()->after('title');
    });
}

public function down(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->dropColumn('excerpt');
    });
}

Evita editar directamente archivos de migración ya ejecutados. Rompes la coherencia con el resto del equipo o con producción. Los cambios se añaden siempre como nuevas migraciones.

Eventos de migración

Cada operación de migración dispara eventos. Todos ellos extienden Illuminate\Database\Events\MigrationEvent.

Clase	Descripción
`Illuminate\Database\Events\DatabaseRefreshed`	Al completarse el comando `migrate:refresh`
`Illuminate\Database\Events\MigrationsStarted`	Justo antes de ejecutarse un lote de migraciones
`Illuminate\Database\Events\MigrationsEnded`	Al completarse el lote de migraciones
`Illuminate\Database\Events\MigrationStarted`	Justo antes de ejecutarse una única migración
`Illuminate\Database\Events\MigrationEnded`	Al completarse una única migración
`Illuminate\Database\Events\NoPendingMigrations`	Cuando el comando detecta que no hay migraciones pendientes
`Illuminate\Database\Events\SchemaDumped`	Al completarse el volcado del esquema
`Illuminate\Database\Events\SchemaLoaded`	Al cargarse un volcado de esquema existente

Por ejemplo, puedes escuchar el evento MigrationsEnded para limpiar la caché tras completar las migraciones.

use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;

Event::listen(MigrationsEnded::class, function () {
    Cache::flush();
});

Introducción

Conceptos básicos

Manejo de solicitudes

Base de datos

Autenticación

Helpers y comunicación externa

Pruebas y despliegue

Asistencia de desarrollo con IA

¿Qué son las migraciones?

Creación de un archivo de migración

Estructura de una migración

Principales métodos para definir columnas

Modificadores de columna

Columnas e índices vectoriales

Creación de índices en línea

Ejecución de migraciones

Rollback

Ejemplo práctico: crear la tabla posts

1. Generar el archivo de migración

2. Editar la migración

3. Ejecutar la migración

4. Añadir columnas más tarde

Eventos de migración

Próximos pasos

Seeding de base de datos

Introducción a Eloquent

​¿Qué son las migraciones?

​Creación de un archivo de migración

​Estructura de una migración

​Principales métodos para definir columnas

​Modificadores de columna

​Columnas e índices vectoriales

​Creación de índices en línea

​Ejecución de migraciones

​Rollback

​Ejemplo práctico: crear la tabla posts

​1. Generar el archivo de migración

​2. Editar la migración

​3. Ejecutar la migración

​4. Añadir columnas más tarde

​Eventos de migración

​Próximos pasos

Seeding de base de datos

Introducción a Eloquent

¿Qué son las migraciones?

Creación de un archivo de migración

Estructura de una migración

Principales métodos para definir columnas

Modificadores de columna

Columnas e índices vectoriales

Creación de índices en línea

Ejecución de migraciones

Rollback

Ejemplo práctico: crear la tabla posts

1. Generar el archivo de migración

2. Editar la migración

3. Ejecutar la migración

4. Añadir columnas más tarde

Eventos de migración

Próximos pasos