Building Database Migrations Without a Framework

Versioned migration scripts evolve a database schema in a reproducible order.

The examples focus on the operation itself, including the important distinction: Editing production tables manually is less reproducible than tracked migrations.

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 is a simplified migration example. Use a migration lock and recovery procedure in production; MySQL DDL can implicitly commit.

<?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)");
$version = "2026_10_add_user_index";
$check = $pdo->prepare("SELECT 1 FROM schema_migrations WHERE version = ?");
$check->execute([$version]);
if (!$check->fetchColumn()) {
    $pdo->exec("CREATE INDEX idx_user_active ON users(active)");
    $pdo->prepare("INSERT INTO schema_migrations(version) VALUES (?)")->execute([$version]);
}

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 is a simplified migration example. Use a migration lock and recovery procedure in production; MySQL DDL can implicitly commit. A new migration version has its own recorded identity.

<?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)");
$version = "2026_11_add_user_index";
$check = $pdo->prepare("SELECT 1 FROM schema_migrations WHERE version = ?");
$check->execute([$version]);
if (!$check->fetchColumn()) {
    $pdo->exec("CREATE INDEX idx_user_active ON users(active)");
    $pdo->prepare("INSERT INTO schema_migrations(version) VALUES (?)")->execute([$version]);
}

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 is a simplified migration example. Use a migration lock and recovery procedure in production; MySQL DDL can implicitly commit. A new migration version has its own recorded identity.

<?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)");
$version = "2026_12_add_user_index";
$check = $pdo->prepare("SELECT 1 FROM schema_migrations WHERE version = ?");
$check->execute([$version]);
if (!$check->fetchColumn()) {
    $pdo->exec("CREATE INDEX idx_user_active ON users(active)");
    $pdo->prepare("INSERT INTO schema_migrations(version) VALUES (?)")->execute([$version]);
}

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

MySQL DDL often commits implicitly, so rollback strategies must not assume every schema change is transactional.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Versioned migration scripts evolve a database schema in a reproducible order.
• MySQL DDL often commits implicitly, so rollback strategies must not assume every schema change is transactional.
• Editing production tables manually is less reproducible than tracked migrations.

Use Building Database Migrations Without a Framework when its documented behavior matches the problem. Test the relevant edge cases in your own runtime before deploying it.