Difflock: Lint Laravel Migrations Against Live Schema | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.msaied.com/articles) Difflock: Lint Laravel Migrations and Diff Your Database Schema On this page 1. [ What Is Difflock? ](#what-is-difflock) 2. [ Linting Pending Migrations ](#linting-pending-migrations) 3. [ Recording and Diffing Schema Baselines ](#recording-and-diffing-schema-baselines) 4. [ CI Integration and Migration Guard ](#ci-integration-and-migration-guard) 5. [ MCP Support for AI Coding Agents ](#mcp-support-for-ai-coding-agents) 6. [ Installation ](#installation) 7. [ Key Takeaways ](#key-takeaways) ![Difflock: Lint Laravel Migrations and Diff Your Database Schema](https://cdn.msaied.com/690/f125c0f9698cce9dd5e241f7030543ba.png) [ Laravel ](https://www.msaied.com/articles?category=laravel) [ Composer Pacakge ](https://www.msaied.com/articles?category=composer-pacakge) #Laravel #Migrations #Database #CI/CD #Schema #Linting Difflock: Lint Laravel Migrations and Diff Your Database Schema ================================================================= 20 Sep 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said Table of contents 1. [ 01 What Is Difflock? ](#what-is-difflock) 2. [ 02 Linting Pending Migrations ](#linting-pending-migrations) 3. [ 03 Recording and Diffing Schema Baselines ](#recording-and-diffing-schema-baselines) 4. [ 04 CI Integration and Migration Guard ](#ci-integration-and-migration-guard) 5. [ 05 MCP Support for AI Coding Agents ](#mcp-support-for-ai-coding-agents) 6. [ 06 Installation ](#installation) 7. [ 07 Key Takeaways ](#key-takeaways) What Is Difflock? ----------------- Difflock is a Laravel package by [Rati Rukhadze](https://github.com/Heyosseus) that analyses pending migrations against the live database they will change. Rather than executing migrations against an empty test database, it reads migration source statically and combines that with the real schema and table-size metadata to surface problems before deployment. Linting Pending Migrations -------------------------- Run `difflock:lint` to analyse every pending migration: ```bash php artisan difflock:lint php artisan difflock:lint -v php artisan difflock:lint --rule=drop-column ``` Consider this migration that looks harmless in a pull request: ```php Schema::table('orders', function (Blueprint $table) { $table->string('channel'); $table->foreignId('customer_id')->constrained()->cascadeOnDelete(); $table->string('card_number', 32)->nullable(); $table->index('status'); }); Schema::table('customers', function (Blueprint $table) { $table->dropColumn('legacy_token'); $table->renameColumn('name', 'full_name'); }); ``` On a populated database, Difflock flags the non-null `channel` column (no default, will fail on existing rows), the destructive `dropColumn()`, the rename, and the fact that `cascadeOnDelete()` removes child rows inside the database engine — bypassing model events, observers, and soft deletes. Additional rules cover `change-column` (compares a `->change()` call with the live column definition), `unindexed-foreign-key`, and `redundant-index` (e.g., adding an index on `(status)` when `(status, created_at)` already exists). When no pending migrations exist, the command audits all migration files instead of producing an empty report. Existing projects can accept their current backlog with: ```bash php artisan difflock:lint --all --accept ``` This writes `database/difflock/accepted.json` as a baseline for future findings. Recording and Diffing Schema Baselines -------------------------------------- Difflock records an observed schema rather than rebuilding an expected one from migration history, which avoids interpreting migrations that contain conditionals, loops, or raw SQL. ```bash php artisan difflock:diff --save ``` This writes `database/difflock/schema.json` — commit it to version control. Later runs compare the current connection against that snapshot. You can also compare two configured connections directly: ```bash php artisan difflock:diff --from=staging --to=production ``` The baseline captures tables, columns, indexes, defaults, and foreign keys. It never stores row data or credentials. CI Integration and Migration Guard ---------------------------------- Installing Difflock does not alter `php artisan migrate`. The guard only activates when you use its own command: ```bash php artisan difflock:migrate ``` When findings reach the configured block level, it stops before Laravel writes to the database. Use `--allow-risky` to deliberately bypass the guard; Laravel's `--force` flag remains the separate production confirmation. For CI pipelines, a single command covers both drift detection and migration linting: ```bash - run: php artisan difflock:check --ci ``` Exit codes: `0` = pass, `1` = drift or findings at threshold, `2` = check cannot run. MCP Support for AI Coding Agents -------------------------------- `php artisan difflock:mcp` starts a standalone MCP server over stdio. Its four tools provide table context, migration linting, schema-drift checks, and rule documentation. An AI coding agent can check a migration before writing the file, using the live schema and table statistics. The `difflock:explain` command generates a Markdown briefing for a migration without calling any external API. Installation ------------ Difflock 1.0.0 requires PHP 8.3 and supports Laravel 12 and 13. It works with MySQL, MariaDB, PostgreSQL, and SQLite. ```bash composer require heyosseus/difflock --dev php artisan vendor:publish --tag=difflock-config php artisan difflock:doctor ``` `difflock:doctor` reports the connection, available tables, pending migrations, registered rules, and whether the configured database role can write. Key Takeaways ------------- - Lints migrations against the **live schema**, catching issues an empty test database misses - Detects destructive operations: `dropColumn`, non-null columns on populated tables, cascade deletes - Records JSON schema baselines you can commit and diff across environments or connections - Guards `php artisan migrate` with configurable block levels and CI-friendly exit codes - Exposes MCP tools so AI coding agents can check migrations before writing them to disk - Requires PHP 8.3, supports Laravel 12 and 13, MySQL, MariaDB, PostgreSQL, and SQLite --- Source: [Difflock: Lint Laravel Migrations and Diff Your Schema — Laravel News](https://laravel-news.com/difflock-migration-linter) Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fdifflock-lint-laravel-migrations-and-diff-your-database-schema&text=Difflock%3A+Lint+Laravel+Migrations+and+Diff+Your+Database+Schema) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fdifflock-lint-laravel-migrations-and-diff-your-database-schema) Frequently Asked Questions ---------------------------- 3 questions Q01 Does Difflock modify or execute my migrations when linting them? No. Difflock reads migration source statically without loading or executing it. It combines that static analysis with your live schema and table-size metadata to flag potential issues, leaving your database untouched during the lint step. Q02 Does installing Difflock change how `php artisan migrate` behaves? No. Installing Difflock does not alter the standard `migrate` command. The migration guard only activates when you explicitly run `php artisan difflock:migrate`. You can also bypass the guard with `--allow-risky` when needed. Q03 What does the schema baseline file contain, and is it safe to commit? The `database/difflock/schema.json` baseline contains schema structure — tables, columns, indexes, defaults, and foreign keys. It does not include table rows or database credentials, so it is safe to commit to version control. Continue reading More Articles --------------- [ View all ](https://www.msaied.com/articles) [ ![Livewire v4.4.6 Released: Bug Fixes, Test Improvements, and Alpine v3.17.4](https://cdn.msaied.com/689/454c52282f3ef5d585905e5952ca969c.png) Livewire Laravel Alpine.js ### Livewire v4.4.6 Released: Bug Fixes, Test Improvements, and Alpine v3.17.4 Livewire v4.4.6 ships with 18 changes including validation performance improvements, better test assertions, k... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 21 Sep 2026 3 min read Read ](https://www.msaied.com/articles/livewire-v446-released-bug-fixes-test-improvements-and-alpine-v3174) [ ![Laravel 14: New Features, Breaking Changes, and PHP 8.4 Requirement](https://cdn.msaied.com/688/2dfe8f11b0bef35c0ee6db912004209f.png) Laravel 14 PHP 8.4 Breaking Changes ### Laravel 14: New Features, Breaking Changes, and PHP 8.4 Requirement Laravel 14 is expected in Q1 2027 and will require PHP 8.4. Here is everything known so far from the master br... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 21 Sep 2026 4 min read Read ](https://www.msaied.com/articles/laravel-14-new-features-breaking-changes-and-php-84-requirement) [ ![Building a Laravel Package: Service Providers, Auto-Discovery, and Config Merging](https://cdn.msaied.com/687/e53f819c8f897c1ad12a1df0661a18f7.png) laravel packages service-providers ### Building a Laravel Package: Service Providers, Auto-Discovery, and Config Merging Learn how to build a production-ready Laravel package from scratch — covering service provider design, auto-di... ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) Mohamed Said 21 Sep 2026 1 min read Read ](https://www.msaied.com/articles/building-a-laravel-package-service-providers-auto-discovery-and-config-merging-4) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)