PHPackages                             migralign/laravel-migralign - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. migralign/laravel-migralign

ActiveLibrary[Database & ORM](/categories/database)

migralign/laravel-migralign
===========================

MigrAlign — align live MySQL tables with Laravel migration schema, safely.

v1.0.1(2w ago)265MITPHPPHP ^8.2CI failing

Since May 21Pushed 6d agoCompare

[ Source](https://github.com/mokhdesigns/laravel-migralign)[ Packagist](https://packagist.org/packages/migralign/laravel-migralign)[ Docs](https://github.com/mokhdesigns/laravel-migralign)[ GitHub Sponsors](https://github.com/sponsors/mokhdesigns)[ RSS](/packages/migralign-laravel-migralign/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (6)Versions (3)Used By (0)

 [![MigrAlign](assets/migralign-social-cover.png)](assets/migralign-social-cover.png)

MigrAlign
=========

[](#migralign)

 **Align your database with your migrations.**
 Detect schema drift, add missing columns, auto-apply safe updates, and get guided confirmation for risky changes.

 `composer require migralign/laravel-migralign`

 [Repository](https://github.com/mokhdesigns/laravel-migralign) · [Issues](https://github.com/mokhdesigns/laravel-migralign/issues) · [Security](SECURITY.md)

---

Table of contents
-----------------

[](#table-of-contents)

- [Overview](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [How MigrAlign works](#how-migralign-works)
- [Risk model and behavior](#risk-model-and-behavior)
- [Command reference](#command-reference)
- [Configuration](#configuration)
- [Recommended workflows](#recommended-workflows)
- [Examples](#examples)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)

Overview
--------

[](#overview)

MigrAlign compares your **Laravel migration-defined schema** with the **current MySQL/MariaDB schema** and helps you synchronize differences safely.

It is useful when:

- schema drift appears between migration files and real database state
- teams edit migrations and need a deterministic sync pass
- you want safe automation for additive/low-risk changes with explicit handling for risky changes

Features
--------

[](#features)

- Scans migration intent from `Schema::create()` and `Schema::table()`
- Introspects live schema from `information_schema`
- Computes table/column diffs
- Auto-applies safe changes
- Interactively prompts for risky/destructive changes
- Supports targeted sync by table or migration filename
- Supports dry-run preview and force mode
- Prints final sync report (`applied`, `skipped`, `pending manual`, `errors`)

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11, 12, or 13
- MySQL or MariaDB connection
- Laravel 13 requires PHP 8.3+ (per [Laravel 13 requirements](https://laravel.com/docs/13.x/deployment#server-requirements))

Installation
------------

[](#installation)

Install the package:

```
composer require migralign/laravel-migralign
```

Laravel auto-discovers the service provider; no manual registration is required.

Publish config (optional):

```
php artisan vendor:publish --tag=migralign-config
```

This creates:

- `config/migralign.php`

Quick start
-----------

[](#quick-start)

1. Update your migration files.
2. Preview what would change:

```
php artisan migralign:sync --dry-run
```

3. Apply sync:

```
php artisan migralign:sync
```

How MigrAlign works
-------------------

[](#how-migralign-works)

1. **Scan migration files** from `config('migralign.migrations_path')`
2. **Build expected schema intent** from migration `up()` logic
3. **Read live schema** from MySQL `information_schema`
4. **Compute diff** for tables and columns
5. **Classify risk** for each change
6. **Apply safe changes** automatically (if enabled)
7. **Prompt for risky changes** (or skip/apply/abort)
8. **Print report**

Risk model and behavior
-----------------------

[](#risk-model-and-behavior)

MigrAlign classifies each change into one of:

- `safe`
- `risky`
- `destructive`

### Usually safe

[](#usually-safe)

- add nullable columns
- widen certain column sizes
- non-destructive metadata-level changes

### Usually risky

[](#usually-risky)

- shrinking type/length (example: `VARCHAR(255)` -> `VARCHAR(50)`)
- nullable -> not nullable
- enum contractions
- type family changes with potential conversion problems

### Usually destructive

[](#usually-destructive)

- drop column
- drop table

For risky/destructive changes, MigrAlign shows:

- why the change is risky
- optional pre-check query
- suggested remediation SQL/instructions
- interactive choice: apply / skip / abort

Command reference
-----------------

[](#command-reference)

### Main command

[](#main-command)

```
php artisan migralign:sync
```

### Options

[](#options)

- `--dry-run`
    Show planned changes only, do not apply. Always exits with status `0`, even when differences are found.
- `--force`
    Apply risky/destructive changes without interactive prompts. Also skips pre-check blocking when existing rows would violate the new schema. Use only when you explicitly accept that data risk.
- `--table=users`
    Limit sync to a specific table.
- `--migration=create_users`
    Scan only migrations with matching filename text.
- `--connection=mysql`
    Override DB connection used for introspection/apply.

### Typical command examples

[](#typical-command-examples)

```
# Preview everything
php artisan migralign:sync --dry-run

# Sync only users table
php artisan migralign:sync --table=users

# Preview a subset of migrations
php artisan migralign:sync --dry-run --migration=2024_01_01

# Apply all including risky (no prompts; bypasses pre-check blocking)
php artisan migralign:sync --force
```

Configuration
-------------

[](#configuration)

Default config file:

```
return [
    'migrations_path' => database_path('migrations'),
    'ignored_tables' => [
        'migrations',
        'password_reset_tokens',
        'sessions',
        'cache',
        'cache_locks',
        'jobs',
        'job_batches',
        'failed_jobs',
    ],
    'auto_apply_safe' => true,
    'connection' => null,
];
```

### Config keys

[](#config-keys)

- `migrations_path`
    Path to migration files used to build expected schema.
- `ignored_tables`
    Tables excluded from diffing.
- `auto_apply_safe`
    If `true`, safe changes apply automatically.
- `connection`
    Default DB connection. `null` means Laravel default.

Recommended workflows
---------------------

[](#recommended-workflows)

### Workflow A: Add a new column

[](#workflow-a-add-a-new-column)

When you add a column in migrations (`Schema::create()` or `Schema::table()`):

```
php artisan migralign:sync --dry-run
php artisan migralign:sync
```

If the column is nullable or otherwise safe, it is created automatically.

### Workflow B: Risky schema tightening

[](#workflow-b-risky-schema-tightening)

For changes like `nullable(true)` -> `nullable(false)` or length shrink:

1. run `--dry-run`
2. review pre-checks and remediation
3. backfill/clean data if needed
4. run sync and confirm prompts

### Workflow C: Preview in CI or before deploy

[](#workflow-c-preview-in-ci-or-before-deploy)

Use dry-run locally or in pipelines to **review** planned changes:

```
php artisan migralign:sync --dry-run
```

`--dry-run` always exits successfully (status `0`), even when drift is detected. For CI gates that must fail on drift, parse the command output or add your own wrapper check.

Examples
--------

[](#examples)

### Example 1: New nullable column

[](#example-1-new-nullable-column)

Migration:

```
Schema::table('users', function (Blueprint $table) {
    $table->string('phone', 20)->nullable();
});
```

Result:

- Diff includes `add_column` for `users.phone`
- Sync applies it automatically (safe)

### Example 2: Column removed from migration intent

[](#example-2-column-removed-from-migration-intent)

If a column exists in DB but not in migration intent:

- diff includes `drop_column`
- classified as destructive
- prompt asks whether to apply/skip/abort

### Example 3: Not-null tightening

[](#example-3-not-null-tightening)

Migration intent changes nullable column to not nullable:

- diff includes `modify_column`
- risky classification
- pre-check identifies violating rows when applicable

Limitations
-----------

[](#limitations)

- Current support target is **MySQL/MariaDB only**
- Migration scanning executes migration `up()` logic in recording mode; extremely dynamic migration logic may need extra care
- Destructive actions should always be reviewed in dry-run first

Troubleshooting
---------------

[](#troubleshooting)

### "supports MySQL/MariaDB only"

[](#supports-mysqlmariadb-only)

Your selected connection is not MySQL/MariaDB.
Use `--connection=` with a MySQL connection, or set `migralign.connection`.

### No differences found but you expect changes

[](#no-differences-found-but-you-expect-changes)

- verify migration file is inside `migralign.migrations_path`
- verify `--migration=` filter is not excluding it
- ensure target table is not in `ignored_tables`

### Risky change is blocked or skipped

[](#risky-change-is-blocked-or-skipped)

- run with `--dry-run` first
- follow remediation instructions
- fix data inconsistencies
- run again after fixing data, or use `--force` only if you explicitly accept bypassing prompts and pre-check blocking

FAQ
---

[](#faq)

### Should I edit old historical migrations?

[](#should-i-edit-old-historical-migrations)

Prefer adding new migrations for forward changes.
Editing old migrations can create large drift expectations across environments.

### Is this a replacement for `php artisan migrate`?

[](#is-this-a-replacement-for-php-artisan-migrate)

No. `migrate` applies migration history; MigrAlign aligns current schema intent to live schema through diff + risk controls.

### Can I use this in production?

[](#can-i-use-this-in-production)

Yes, but always run dry-run first and review destructive/risky operations.

Contributing
------------

[](#contributing)

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test commands, and pull request guidelines.

Report security issues privately — see [SECURITY.md](SECURITY.md).

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance98

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

19d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8aa092c27a5563bfb4a0fcb4d602f0857db0fc1947f2a6ce70e40a2ab055426b?d=identicon)[Mokhtar ali](/maintainers/Mokhtar%20ali)

---

Top Contributors

[![Mokhtarali12](https://avatars.githubusercontent.com/u/214580268?v=4)](https://github.com/Mokhtarali12 "Mokhtarali12 (6 commits)")[![mokhdesigns](https://avatars.githubusercontent.com/u/41319367?v=4)](https://github.com/mokhdesigns "mokhdesigns (2 commits)")

---

Tags

laravelschemadatabasemysqlmigrationssync

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/migralign-laravel-migralign/health.svg)

```
[![Health](https://phpackages.com/badges/migralign-laravel-migralign/health.svg)](https://phpackages.com/packages/migralign-laravel-migralign)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[itpathsolutions/dbstan

Database Standardization and Analysis Tool for Laravel

442.1k](/packages/itpathsolutions-dbstan)[orptech/laravel-migration-partition

Laravel extensions that extends Illuminate to enable partitioned table creation within Laravel migrations.

3628.3k](/packages/orptech-laravel-migration-partition)[dragon-code/laravel-data-dumper

Adding data from certain tables when executing the `php artisan schema:dump` console command

3420.8k](/packages/dragon-code-laravel-data-dumper)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)