1 · Compare the schema

TL;DR

Objective — before touching anything, find out exactly what the new release will change in the database, so a quiet DROP COLUMN or DROP TABLE can never reach production by surprise.

User part + done-when

👤 User part — small but real: a person reads the vendor changelog and gives explicit approval if the diff shows a destructive change (a drop or a truncate). The migration checks and the Atlas diff are agent-runnable.

Done when every pending migration is listed, the Atlas diff matches Laravel’s own --pretend SQL, and each change is classified — with destructive changes flagged for backup.  ·  ⏱ ~20–30 min  ·  🔀 mixed (👤 changelog + approval, 🤖 the diffing).

Background

A vendor update is two things at once: new files and new migrations. The files you can branch and revert. The migrations touch live data — and that is where the irreversible damage hides. Comparing the schema first answers one question with certainty: “what will change, and can any of it lose data?”

You compare against your frozen baseline — the author-vX.X.X snapshot you tagged when you first imported the app. Laravel migrations track intent (the files you wrote); a schema-diff tool like Atlas tracks reality (the actual tables and columns). You want both, because vendor installers and manual hotfixes can change the database without ever writing a migration file — and only a reality-based diff catches that drift.

flowchart TD
  A["migrate:status<br/>what's pending?"] --> B["migrate --pretend<br/>preview the SQL"]
  B --> C["atlas schema diff<br/>reality vs baseline"]
  C --> D{"Outputs<br/>match?"}
  D -->|Yes| E["Classify by risk"]
  D -->|No| F["Schema drift —<br/>investigate"]
  E --> G{"Any drop or<br/>truncate?"}
  G -->|No| H["Safe to apply"]
  G -->|Yes| I["Back up + get approval"]

Steps

1. Read the vendor changelog first

Before any command, find out what the vendor says changed. The changelog tells you which tables and features to expect in the diff — so an unexpected change stands out instead of blending in.

Who does this

👤 User opens the vendor’s changelog (CodeCanyon item page or the bundled CHANGELOG) and notes the headline DB-affecting changes. An agent can’t judge “is this feature one we use?” — that’s a product call.

1. Note what the release claims to touch. New tables, renamed columns, dropped features, security patches. Write the short list somewhere you’ll see it while diffing.

   • ✅ You have a one-line summary of what the vendor says this release changes in the database.

A changelog is a claim, not proof — the diff in the next steps is what you actually trust. But reading it first turns the diff from a wall of SQL into a checklist you can confirm against.

2. List the pending migrations

Find every migration the new release will run but yours has not. This is the file-level view: what the vendor intends to do.

1. Check migration status, then isolate the pending ones.

   php artisan migrate:status --no-ansi
   php artisan migrate:status --no-ansi | grep "No"
   # Expected: every "Ran? No" row is a migration this update will apply

   • ✅ You have the list of pending migrations; an all-Ran? Yes result means there’s nothing new at the file level (skip to step 4).

2. Document each pending migration — its file, what it creates or alters, and a first-pass risk read.

   Field	Example
   File	2024_11_02_add_timezone_to_users_table.php
   Touches	users table — adds timezone column
   Risk	Low (ADD COLUMN)

   • ✅ Each pending migration has a row capturing file, what it touches, and a first risk read.

3. Preview the SQL with --pretend

--pretend prints the SQL a migration would run without running it. This is the safest way to read intent — no rows change, but you see every statement.

1. Print the migration SQL without executing it, and save the output to compare against the Atlas diff.

   php artisan migrate --pretend
   # Expected: the CREATE / ALTER statements that WOULD run — nothing is applied

   • ✅ You have the exact SQL Laravel intends to run, saved for the match check in step 5.

Scan the diff for danger words

Pipe the vendor’s migration diff through grep to surface the risky verbs fast: git diff author-vX.X.X..author-vY.Y.Y -- database/migrations/ | grep -iE "drop|truncate|rename". Anything that prints is a change you must approve deliberately.

4. Run the Atlas schema diff

Atlas compares the actual database state against your tagged baseline. This catches changes that never appear in a migration file — installer-created tables, manual SQL, vendor scripts.

1. Diff the post-update state against your frozen baseline tag.

   atlas schema diff \
     --from "atlas://CUSTOJO?tag=author-vX.X.X" \
     --to   "atlas://CUSTOJO?tag=author-vY.Y.Y"
   # Expected: a list of CREATE / ALTER / DROP statements — the real delta

   • ✅ Atlas prints the concrete schema delta between your baseline and the new release.

2. Open the visual diff in the browser when the text output is dense.

   atlas schema diff \
     --from "atlas://CUSTOJO?tag=author-vX.X.X" \
     --to   "atlas://CUSTOJO?tag=author-vY.Y.Y" -w
   # Expected: a browser tab opens with a side-by-side visual comparison

   • ✅ The visual diff renders, making added/removed/modified tables easy to scan.

Match the database driver exactly

Atlas needs the right driver prefix and dev image: maria:// + docker://mariadb/latest/dev for MariaDB, mysql:// + docker://mysql/8/dev for MySQL. Run mysql -u root -e "SELECT VERSION();" to confirm — using the wrong one produces subtle, wrong diffs. If the password has @, #, or /, URL-encode it (@→%40, #→%23, /→%2F).

5. Confirm the two views agree

Laravel’s --pretend (intent) and Atlas’s diff (reality) should describe the same change. A mismatch means the database holds something your migrations don’t — schema drift you must explain before you apply anything.

1. Line up the two outputs and confirm each change appears in both.

   Laravel --pretend	Atlas diff	Match?
   CREATE users_zaj	+ users_zaj	✅
   ALTER settings.value	~ settings.value	✅
   (nothing)	DROP old_table	❌ investigate

   • ✅ Every change is present in both views; nothing appears in one but not the other.

2. If they disagree, capture the drift as a migration rather than ignoring it — then re-diff until both views agree.

   atlas migrate diff capture_drift \
     --dir "file://database/migrations" \
     --to "mysql://root:@localhost:3306/database" \
     --dev-url "docker://mysql/8/dev"
   # Expected: a new migration file describing the un-tracked change

   • ✅ Drift is captured in a migration (or explained), and a re-run of the diff shows the two views now agree.

6. Classify every change by risk

Sort each confirmed change into a risk tier. The tier decides what happens next: low-risk changes proceed, destructive ones force a backup and explicit approval before Workflow step 2.

Who does this

👤 User approves any 🔴 destructive change (a DROP or TRUNCATE) before it’s allowed to proceed. An agent classifies and flags, but “yes, drop that table” is a human decision with no undo.

1. Assign a risk tier to each change and decide the action it triggers.

   Change	Risk	Action
   CREATE TABLE	🟢 Low	Proceed
   ADD COLUMN (nullable)	🟢 Low	Proceed
   ADD COLUMN (not null)	🟡 Medium	Verify a default exists
   MODIFY COLUMN	🟡 Medium	Test on staging
   RENAME	🟡 Medium	Verify code references
   DROP COLUMN	🔴 High	Back up first
   DROP TABLE	🔴 Critical	Backup + explicit approval
   TRUNCATE	🔴 Critical	Block until reviewed

   • ✅ Every change has a risk tier and a decided action; no change is unclassified.

2. Record the decision so the update has an audit trail — what changes, whether any are destructive, and whether a backup is required.

   • ✅ A short written record names the changes, flags any destructive ones, and states whether a pre-update backup is needed.

A destructive change is a full stop, not a speed bump

If the diff shows any DROP or TRUNCATE, do not proceed to applying the update until you have (1) a database backup, (2) tested the change on staging, and (3) explicit human approval. The point of comparing first is to never discover a dropped table after it’s gone.

Checklist

Do not mark this step done until every box below is checked.

• 👤 Changelog read — the vendor’s claimed DB changes are noted and available while diffing.
• 🤖 Pending migrations listed — migrate:status ran; each pending migration documented (file, touches, risk).
• 🤖 SQL previewed — migrate --pretend output saved for the match check.
• 🤖 Atlas diff run — the new release diffed against the author-vX.X.X baseline; driver matched.
• 🤖 Views agree — Laravel --pretend and Atlas diff describe the same change, or drift is captured.
• 🔀 Changes classified — every change has a risk tier; destructive changes flagged for backup + 👤 approval.

→Next step

Apply the update