Managing Database Migrations in PHP

Track and apply ordered schema changes using a migration log table.

The examples focus on the operation itself, including the important distinction: A dump restores a snapshot; migrations advance schema versions.

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

This step reads applied migration versions; the actual runner must lock, apply new scripts in order and record success.

<?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]
);
$pdo->exec("CREATE TABLE IF NOT EXISTS schema_migrations (version VARCHAR(80) PRIMARY KEY)");
$stmt = $pdo->query("SELECT version FROM schema_migrations ORDER BY version");
foreach ($stmt->fetchAll(PDO::FETCH_COLUMN) as $version) { echo $version . PHP_EOL; }

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

Example 2: Checking Behavior

This step reads applied migration versions; the actual runner must lock, apply new scripts in order and record success. The migration log can be filtered to review recent deployments.

<?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]
);
$pdo->exec("CREATE TABLE IF NOT EXISTS schema_migrations (version VARCHAR(80) PRIMARY KEY)");
$stmt = $pdo->query("SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 5");
foreach ($stmt->fetchAll(PDO::FETCH_COLUMN) as $version) { echo $version . PHP_EOL; }

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

Example 3: Practical Example

This step reads applied migration versions; the actual runner must lock, apply new scripts in order and record success. The migration log can be filtered to review recent deployments.

<?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]
);
$pdo->exec("CREATE TABLE IF NOT EXISTS schema_migrations (version VARCHAR(80) PRIMARY KEY)");
$stmt = $pdo->query("SELECT version FROM schema_migrations WHERE version LIKE '2026_%' ORDER BY version");
foreach ($stmt->fetchAll(PDO::FETCH_COLUMN) as $version) { echo $version . PHP_EOL; }

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

Only one migration runner should update the schema at a time; verify existing schema before applying changes.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Track and apply ordered schema changes using a migration log table.
• Only one migration runner should update the schema at a time; verify existing schema before applying changes.
• A dump restores a snapshot; migrations advance schema versions.

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