Migracje w Laravelu: dodanie kolumny, rollback i usuwanie

Migracje wersjonują schemat bazy tak, jak Git wersjonuje kod: każda zmiana to jeden plik, odtwarzalny na dowolnym środowisku. Codzienną pracę pokrywają trzy operacje: dodanie kolumny do istniejącej tabeli, wycofanie migracji i usunięcie pliku, który nigdy nie powinien powstać.

Artykuł ze ścieżki Programowanie webowe. Wszystkie komendy i ich wyniki uruchomiono na Laravelu 13.30.1 z PHP 8.4.25.

Tworzenie migracji

Komenda trzyma się konwencji nazewnictwa, od której zależy zawartość wygenerowanego pliku:

php artisan make:migration create_tasks_table

Nazwa zaczyna się od create, po którym następuje nazwa tabeli w liczbie mnogiej i table. Laravel rozpoznaje ten wzorzec i wstępnie wypełnia Schema::create() metodami id() i timestamps(), kolumna title została tu dodana dla przykładu, a wygenerowane komentarze usunięte:

<?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('tasks', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->timestamps();
        });
    }

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

Jeśli tabela ma trzymać daty utworzenia i modyfikacji, dodaje je $table->timestamps(): ich brak wywołuje błąd „Unknown column 'updated_at’”.

Uruchomienie migracji tworzy tabelę:

php artisan migrate

Dodanie kolumny do istniejącej tabeli

Kiedy schemat już stoi, resztę robią typowe zapytania Eloquenta. Nigdy nie zmieniaj migracji, która już się wykonała: koledzy z zespołu i serwery ją odtworzyli i drugi raz tego nie zrobią. Utwórz nową migrację i wskaż tabelę opcją --table:

php artisan make:migration add_notes_to_tasks_table --table=tasks

Wygenerowany plik zawiera puste Schema::table() w obie strony. Uzupełnij oba: kolumnę w up(), jej usunięcie w down().

public function up(): void
{
    Schema::table('tasks', function (Blueprint $table) {
        $table->text('notes')->nullable()->after('title');
    });
}

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

php artisan migrate

  2026_09_02_194036_add_notes_to_tasks_table .................... 47.43ms DONE

Warto przypomnieć tu o dwóch środkach ostrożności.

Zrób kolumnę nullowalną albo nadaj jej wartość domyślną. W tabeli, w której są już wiersze, kolumna NOT NULL bez wartości domyślnej wywala migrację: baza nie wie, co wpisać w istniejących wierszach.

Zawsze pisz down(). To ona sprawia, że migracja jest odwracalna. Migracja bez down() zamienia najdrobniejsze cofnięcie w ręczną robotę.

Wycofanie migracji, która już się wykonała

Zacznij od sprawdzenia, na czym stoisz. migrate:status wypisuje każdą migrację razem z jej partią i stanem:

php artisan migrate:status

  2026_09_02_100000_create_tasks_table ............................... [1] Ran
  2026_09_02_194036_add_notes_to_tasks_table ......................... Pending

Migracja w stanie Pending nigdy się nie wykonała: jej plik możesz skasować od razu. Migrację Ran trzeba najpierw wycofać.

# cofa tylko ostatnią migrację
php artisan migrate:rollback --step=1

# cofa całą ostatnią partię
php artisan migrate:rollback

Rollback uruchamia metodę down(). W powyższym przykładzie kolumna notes faktycznie znika z tabeli, a migracja wraca do stanu Pending. Dopiero wtedy, nie wcześniej, wolno usunąć plik.

Istnieją jeszcze dwie pokrewne komendy, zarezerwowane dla środowiska deweloperskiego:

# cofa wszystko i odtwarza wszystko od nowa
php artisan migrate:refresh

# usuwa wszystkie tabele, a potem odtwarza wszystko od nowa
php artisan migrate:fresh

Usuwanie migracji

Nie ma czegoś takiego jak make:migration --delete: migrację usuwa się, kasując jej plik w database/migrations, czyli w katalogu zwracanym przez database_path() spośród ścieżek aplikacji. Jedyne pytanie brzmi: czy ta migracja już się wykonała.

Nigdy się nie wykonała (stan Pending): usuń plik i tyle.

rm database/migrations/2026_09_02_194036_add_notes_to_tasks_table.php

Już się wykonała (stan Ran): najpierw ją wycofaj, potem usuń plik.

php artisan migrate:rollback --step=1
rm database/migrations/2026_09_02_194036_add_notes_to_tasks_table.php

Zmiana istniejącej kolumny

Żeby zmienić typ, długość albo nullowalność, zadeklaruj kolumnę ponownie i dopisz change():

public function up(): void
{
    Schema::table('tasks', function (Blueprint $table) {
        $table->string('title', 500)->change();
    });
}

Dobra wiadomość dla wracających ze starszej wersji: pakiet doctrine/dbal, przez lata obowiązkowy przy tej operacji, od Laravela 11 nie jest już potrzebny. Sprawdzone na Laravelu 13.30.1, gdzie change() działa bez dodatkowej zależności.