PHP Database Migrations and Rollbacks

A schema migration and its rollback describe how an application changes database structure between versions.

The examples focus on the operation itself, including the important distinction: A transaction rollback undoes DML; schema rollback may need new DDL.

What It Does

Use the examples below to observe the behavior on a small dataset before extending it to application code.

Before You Start

The examples use PHP 8.2+ features where shown. Database snippets require the corresponding PDO driver, demo tables, and credentials configured outside source code.

Example 1: Basic Use

Rollback for MySQL DDL often needs explicit reverse DDL or a forward correction; a SQL transaction alone is insufficient.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
$row = $pdo->query("SELECT COUNT(*) FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'users' AND column_name = 'last_login_at'")->fetchColumn();
echo (int) $row ? "Column exists; review down migration" : "Column absent";

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Example 2: Checking Behavior

Rollback for MySQL DDL often needs explicit reverse DDL or a forward correction; a SQL transaction alone is insufficient. A down migration should confirm its target schema before applying any destructive DDL.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
$row = $pdo->query("SELECT COUNT(*) FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'users' AND column_name = 'account_timezone'")->fetchColumn();
echo (int) $row ? "Column exists; review down migration" : "Column absent";

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Example 3: Practical Example

Rollback for MySQL DDL often needs explicit reverse DDL or a forward correction; a SQL transaction alone is insufficient. A down migration should confirm its target schema before applying any destructive DDL.

<?php
$pdo = new PDO(
    "mysql:host=" . (getenv("DB_HOST") ?: "127.0.0.1") . ";dbname=" . (getenv("DB_NAME") ?: "demo") . ";charset=utf8mb4",
    getenv("DB_USER") ?: "app",
    getenv("DB_PASSWORD") ?: "",
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, PDO::ATTR_EMULATE_PREPARES => false]
);
$row = $pdo->query("SELECT COUNT(*) FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = 'users' AND column_name = 'deleted_at'")->fetchColumn();
echo (int) $row ? "Column exists; review down migration" : "Column absent";

This example is meant for a configured application environment; output depends on the installed extension, external service, or database contents.

Important Behavior and Edge Cases

Some DDL cannot be reversed without data loss; backups and forward fixes may be safer than a down migration.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• A schema migration and its rollback describe how an application changes database structure between versions.
• Some DDL cannot be reversed without data loss; backups and forward fixes may be safer than a down migration.
• A transaction rollback undoes DML; schema rollback may need new DDL.

Use PHP Database Migrations and Rollbacks when its documented behavior matches the problem. Test the relevant edge cases in your own runtime before deploying it.