⬡ Lacelium
⌘K
Version 2.x ▾

Migrations

Introduction

Migrations are like version control for your database, allowing your team to define and share the application's database schema definition. If you have ever had to tell a teammate to manually add a column to their local database schema after pulling your changes from version control, you've faced the problem that database migrations solve.

The Lacelium Schema facade provides database agnostic support for creating and manipulating tables across all of Lacelium's supported database systems.

Generating Migrations

You may use the make:migration console command to generate a database migration. The new migration will be placed in your database/migrations directory. Each migration filename contains a timestamp that allows Lacelium to determine the order of the migrations:

php console make:migration create_flights_table

Migration Structure

A migration class contains two methods: up and down. The up method is used to add new tables, columns, or indexes to your database, while the down method should reverse the operations performed by the up method.

Within both of these methods, you may use the Lacelium schema builder to expressively create and modify tables:

<?php

declare(strict_types=1);

use Lacelium\Core\Database\Migration;
use Lacelium\Core\Database\Schema;
use Illuminate\Database\Schema\Blueprint;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->string('flight_number', 32)->unique();
            $table->string('airline');
            $table->decimal('price', 8, 2);
            $table->boolean('is_active')->default(true);
            $table->json('metadata')->nullable();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('flights');
    }
};

Available Column Types

The schema builder blueprint offers a variety of methods that correspond to the different types of columns you can add to your database tables:

  • $table->id();: Auto-incrementing UNSIGNED BIGINT primary key.
  • $table->string('name', 100);: VARCHAR equivalent column with optional length.
  • $table->text('description');: TEXT equivalent column.
  • $table->integer('votes');: INTEGER equivalent column.
  • $table->decimal('amount', 8, 2);: DECIMAL equivalent with precision and scale.
  • $table->boolean('confirmed');: BOOLEAN equivalent column.
  • $table->json('settings');: JSON equivalent column.
  • $table->timestamps();: Adds nullable created_at and updated_at TIMESTAMP columns.

Column Modifiers

In addition to the column types listed above, there are several column "modifiers" you may use while adding a column to a database table:

// Allow NULL values to be inserted into the column:
$table->string('email')->nullable();

// Specify a "default" value for the column:
$table->string('status')->default('pending');

// Set integer columns as UNSIGNED:
$table->unsignedInteger('votes')->default(0);

// Add unique index:
$table->string('sku')->unique();

Running Migrations

To run all of your outstanding migrations, execute the migrate console command:

php console migrate

Rolling Back Migrations

To roll back the latest migration operation, you may use the rollback command. This command rolls back the last "batch" of migrations, which may include multiple migration files:

php console migrate:rollback

# Roll back a specific number of migrations:
php console migrate:rollback --step=3

Fresh Database Reset

The migrate:fresh command will drop all tables from the database and then execute the migrate command:

php console migrate:fresh

# Reset and seed sample data:
php console migrate:fresh --seed

Next Steps