You might have noticed that every modern PHP framework comes with a migration system. Because of this, a lot of developers fall into the trap of thinking that "migrations" are a specific feature of a framework like Laravel or Symfony. They think it's some magic black box that manages their database.

Migrations aren't a framework feature; they're just version control for your schema

Here is why that misconception is dangerous: it makes you feel like you can't manage a professional database unless you're using a heavy framework. Let's look at a real scenario. Imagine you're working on a project with two other developers. You decide the users table needs a last_login_at timestamp. You run ALTER TABLE users ADD COLUMN last_login_at DATETIME; directly in your database GUI, update your PHP code to use that column, and push your changes to GitHub.

Your teammates pull the code. Immediately, their local environments crash. Why? Because their local databases don't have that column. You send them the SQL snippet over Slack, and they run it manually. Then, you deploy to production and forget to run that same snippet. The site goes down. This manual "hand-off" of SQL is fragile and prone to human error.

A migration is simply a way to track which SQL scripts have already been executed against a specific database instance. It's exactly like Git, but for your table structures. Instead of sharing SQL snippets, you share a folder of scripts and a small piece of code that knows how to run them in order.

Moving from manual SQL to a tracked migration system

To do this without a framework, you only need two things: a table to track history and a directory of scripts. First, you create a table called migrations. It only needs two columns: an id and a migration name (the filename). This table acts as the "source of truth" for the current state of the database.

I prefer keeping my migrations as plain .sql files in a folder, numbered sequentially. For example:

• 001_create_users_table.sql
• 002_add_last_login_to_users.sql
• 003_create_posts_table.sql

Now, instead of running these manually, you write a simple PHP script (the "Runner") that follows this logic: 1. Scan the migrations/ folder for all files. 2. Query the migrations table to see which files have already been recorded. 3. Compare the two lists. 4. Execute the SQL inside any file that exists in the folder but not in the table. 5. After each successful execution, insert that filename into the migrations table.

// A simplified glimpse at the runner logic
$files = glob('migrations/*.sql');
$executed = $pdo->query("SELECT migration FROM migrations")->fetchAll(PDO::FETCH_COLUMN);

foreach ($files as $file) {
    $filename = basename($file);
    if (!in_array($filename, $executed)) {
        $sql = file_get_contents($file);
        $pdo->exec($sql);
        
        $stmt = $pdo->prepare("INSERT INTO migrations (migration) VALUES (?)");
        $stmt->execute([$filename]);
        
        echo "Applied: $filename\n";
    }
}

I've used this exact pattern in legacy projects where adding a 50MB framework just to handle database updates would have been overkill. It's transparent, it's fast, and it ensures that every single environment—from your laptop to the production server—is running the exact same schema.

📋 Practical Task

Build a Schema Versioning System for a Blog Database

Your goal is to create a functional, framework-less migration system for a simple blog. Complete the following steps:

• The Tracking Table: Write the SQL to create a migrations table that stores the filename of executed scripts.
• The Migration Files: Create a directory named migrations/. Inside, create two files:
  • 001_create_posts.sql (Create a posts table with id, title, and content).
  • 002_add_status_to_posts.sql (Add a status VARCHAR column to the posts table).
• The Runner Script: Write a PHP script that uses PDO to connect to your database, reads the migrations/ folder, and executes any pending SQL files while recording their completion in the migrations table.

Test your system: Run the script once to apply both migrations. Run it a second time to verify that no SQL is executed twice and no duplicate entries are added to your tracking table.