5 · Verify migrations & schema

TL;DR

Objective — prove the install is genuinely complete: confirm every migration ran (modules included), troubleshoot pending ones the right way, capture a normalized schema baseline for cross-environment diffs, then run the 11-point gate that shows the app actually works.

User part + done-when

👤 User part — log into the app in a browser and confirm the dashboard, navigation, images, and CSS all load (an agent can’t visually confirm the rendered UI). The migration checks, schema baseline, and 11-point gate are all terminal-runnable.

Done when migrate:status shows no pending migrations (modules counted), any duplicate/empty vendor migrations are resolved via the migrations table, a normalized local.sql baseline is written, the 11-point gate is all green, and the browser login + dashboard check passes with a clean log.  ·  ⏱ ~20–35 min  ·  🔀 mixed (🤖 verification + baseline, 👤 login check).

Background

The installer says it finished — now prove it. Pending migrations are the #1 cause of deploy failures, so catch them locally where a fix is cheap, then snapshot the schema as your drift baseline.

Steps

1. Check migration status

Start with the cheap top-level check.

1. Scan for any pending migration.

   php artisan migrate:status --no-ansi | grep "Pending" && echo "PENDING FOUND" || echo "All migrations ran"
   # Expected: "All migrations ran"

   • ✅ No Pending rows surface.

2. Verify the migration count — modules included

Apps using nwidart/laravel-modules often hide migrations inside individual module directories. Miss those and a “files = ran” match hides real drift.

1. Count ran migrations against total files, modules included.

   RAN=$(php artisan migrate:status --no-ansi 2>/dev/null | grep -c 'Ran')
   MAIN_FILES=$(ls -1 database/migrations/*.php 2>/dev/null | wc -l | xargs)
   if [ -d Modules ]; then
     MODULE_FILES=$(find Modules -type f -name '*.php' -path '*/database/migrations/*' 2>/dev/null | wc -l | xargs)
     TOTAL=$((MAIN_FILES + MODULE_FILES))
   else
     TOTAL=$MAIN_FILES
   fi
   echo "Ran: $RAN  |  Total files: $TOTAL"
   [ "$RAN" -eq "$TOTAL" ] && echo "✅ Exact match" || echo "⚠️  Investigate $((TOTAL - RAN)) migration(s)"
   # Expected: "✅ Exact match" (or a small gap to investigate in §3)

   • ✅ Ran count matches the total migration files (or the gap is understood).

2. Read the result against this table.

   Ran vs Total	Status	Action
   Equal	✅ Healthy	Proceed
   Ran < Total by 1–3	⚠️ Check pending	Investigate (§3) — may be cosmetic
   Ran ≪ Total (big gap)	🔴 Problem	Stop; fix before deploying
   Ran > Total	ℹ️ Vendor update removed files	Not a blocker; note which records reference missing files

   • ✅ The gap (if any) is classified.

Migrations > tables is normal — not a partial install

Many migrations ALTER existing tables instead of creating new ones, so a 400-migration install might produce 250 tables. The authoritative check is migrate:status, not table count. Likewise, all rows in batch [1] is the healthy signal for a fresh install — multi-batch states ([1],[2],…) just mean migrations ran at different times.

3. Investigate pending migrations

Laravel tracks migrations by filename in the migrations table, not by inspecting the schema. There are four reasons one stays pending.

1. Diagnose why a migration is pending.

   Reason	How to verify	Action
   An error occurred	php artisan migrate --verbose shows a red error	Fix the migration error
   up() is empty/commented	Open the file	Safe to skip (mark as ran)
   Conditional logic skipped it	if (!Schema::hasTable(...)) guard	Confirm the table/column already exists
   Class not found	use references a missing class	Confirm the class exists

   • ✅ The cause of each pending migration is identified.

2. Run the genuinely-pending ones and re-check.

   php artisan migrate --verbose   # reveals hidden errors
   php artisan migrate             # run the genuinely-pending ones
   php artisan migrate:status --no-ansi | grep "Pending" || echo "All clear"
   # Expected: "All clear"

   • ✅ No real pending migrations remain.

Edit the database, never vendor migration files

CodeCanyon vendors often ship duplicate migrations for bug fixes — if a later migration did the work and ran, the original showing “Pending” is cosmetic. Mark such rows as ran by inserting into the migrations table; never edit the vendor file (updates overwrite it):

-- Backup first (local only — cheap insurance before any manual write)
CREATE TABLE IF NOT EXISTS _backup_migrations AS SELECT * FROM migrations;

INSERT INTO migrations (migration, batch) VALUES ('2024_01_01_000000_duplicate_name', 999);

Add Schema::hasTable() guards only to your own custom migrations, not vendor ones.

The same filename-tracking quirk causes a different problem once you deploy:

Stale server Composer cache (deploy-time diagnosis)

On shared hosting (Hostinger hPanel / cPanel), a server’s stale Composer cache from a previous project can leave extra vendor migration files versus local — even with an identical composer.lock — causing “Table already exists” on deploy. Diagnose after deploying by comparing vendor migration dirs local-vs-server.

# Local
ls vendor/<vendor>/<package>/database/migrations/

# Server (over SSH — use your Deployer/SSH alias)
dep ssh staging "ls ~/domains/<DOMAIN>/deploy/current/vendor/<vendor>/<package>/database/migrations/"
# Expected: identical file lists; MORE files on the server = stale cache

Fix by marking the extras as ran on the server, or by clearing the server’s Composer file cache:

# Option A — mark each extra migration as ran (batch 999) on the server
dep ssh staging "cd ~/domains/<DOMAIN>/deploy/current && php artisan tinker --execute=\"\
  DB::table('migrations')->insertOrIgnore(['migration' => '<MIGRATION_FILENAME_NO_PHP>', 'batch' => 999]);\""

   # Option B — rotate the server's Composer file cache, then recreate the directory
   dep ssh staging 'CACHE_DIR=~/.cache/composer/files; [ -d "$CACHE_DIR" ] && mv "$CACHE_DIR" "${CACHE_DIR}_backup_$(date +%Y%m%d%H%M%S)"; mkdir -p "$CACHE_DIR"'
   # Expected: subsequent deploy migrates cleanly with no 'Table already exists'

Prevention: always commit composer.lock, clear the server Composer cache before the first deploy, and re-compare migration counts local-vs-server after each deploy.

4. Capture a normalized schema baseline

A schema baseline turns future drift into a readable diff. Create the structure and export schema-only.

1. Export a schema-only dump (Atlas if installed, otherwise mariadb-dump/mysqldump --no-data).

   mkdir -p Admin-Local/1-Project/3-ProjectDB/{1-Current,2-Snapshots,3-VendorOriginal}
   DB_NAME=$(grep DB_DATABASE .env | cut -d= -f2)
   
   # Atlas if installed (cleaner output); otherwise mariadb-dump/mysqldump --no-data
   if command -v atlas >/dev/null 2>&1; then
     atlas schema inspect -u "mysql://root:@127.0.0.1:3306/${DB_NAME}" --format '{{ sql . }}' \
       > Admin-Local/1-Project/3-ProjectDB/1-Current/local.sql
   else
     DUMP=$(command -v mariadb-dump || command -v mysqldump)
     "$DUMP" -h 127.0.0.1 -u root --no-data "${DB_NAME}" \
       > Admin-Local/1-Project/3-ProjectDB/1-Current/local.sql
   fi
   # Expected: local.sql written with the schema (no data)

   • ✅ A schema-only local.sql exists under 1-Current/.

2. Normalize the dump so only real drift surfaces — strip environment-specific noise idempotently.

   BASELINE="Admin-Local/1-Project/3-ProjectDB/1-Current/local.sql"
   sed \
     -e '/^-- MariaDB dump/d' \
     -e '/^-- MySQL dump/d' \
     -e '/^-- Host:/d' \
     -e '/^-- Server version/d' \
     -e '/^-- Dump completed/d' \
     -e '/^\/\*M!999999/d' \
     -e '/^\/\*M!100616/d' \
     -e 's/ AUTO_INCREMENT=[0-9]*//' \
     -e 's|/\*!40101 SET character_set_client = utf8 \*/|/*!40101 SET character_set_client = utf8mb4 */|' \
     "$BASELINE" > "${BASELINE}.tmp" && mv "${BASELINE}.tmp" "$BASELINE"
   # Expected: dump-date/host/version/AUTO_INCREMENT noise removed; real structure untouched

   • ✅ The baseline carries no environment noise — only structural definitions.

3. Snapshot the vendor original (first setup only) and verify the baseline.

   # First setup of this vendor version only:
   # cp …/1-Current/local.sql …/3-VendorOriginal/v[VERSION].sql
   
   BASELINE="Admin-Local/1-Project/3-ProjectDB/1-Current/local.sql"
   [ -s "$BASELINE" ] && echo "✅ $(wc -l < "$BASELINE") lines"
   grep -c "^CREATE TABLE" "$BASELINE"   # should match the DB table count
   grep -c "^-- Host:\|^-- Server version\|AUTO_INCREMENT=" "$BASELINE"   # expect 0 noise lines
   # Expected: a non-empty line count, CREATE TABLE count = DB tables, 0 noise lines

   • ✅ Baseline is non-empty, CREATE TABLE count matches the DB, and 0 noise lines remain.

Format consistency across environments is non-negotiable

Whatever command you run locally, the exact same command must run on staging/production. --no-data is the only flag you should add — never --skip-comments or --compact, which strip structural markers and pollute every future diff. The normalization above does not touch real drift: different column types/constraints, missing or extra tables, index differences.

One class of “drift” is a false alarm worth pre-empting:

Per-install random defaults (Froiden/CodeCanyon pattern)

Some installers generate a random DEFAULT per install (e.g. societies.hash gets a different md5 each time). These are functionally equivalent — app code always supplies the value on INSERT — so document them in _CUSTOMIZATIONS.md under a “per-install random defaults (ignore in diffs)” heading so they never look like real drift.

5. Run the 11-point gate

This one-liner proves the app is genuinely functional before any commit or deploy — then a human confirms the rendered UI.

Who does this

👤 User logs in with the admin credentials and confirms the dashboard, navigation, images (symlinks), and CSS (build) all load with no console errors — a visual check only a person can make. The agent runs the gate command and log scan.

1. Run the 11-point gate.

   DB_NAME=$(grep DB_DATABASE .env | cut -d= -f2)
   echo "1. Vendor:       $([ -f vendor/autoload.php ] && echo OK || echo MISSING)"
   echo "2. Node:         $([ -d node_modules ] && echo OK || echo MISSING)"
   echo "3. Build:        $([ -f public/build/manifest.json ] && echo OK || echo MISSING)"
   echo "4. Storage link: $([ -L public/storage ] && echo Linked || echo Broken)"
   echo "5. Installer:    $([ -f storage/installed ] && echo Present || echo MISSING)"
   echo "6. Database:     $(php artisan db:show >/dev/null 2>&1 && echo Connected || echo Failed)"
   echo "7. Tables:       $(mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';" 2>/dev/null)"
   echo "8. Migrations:   $(php artisan migrate:status --no-ansi 2>/dev/null | grep -q Pending && echo 'PENDING — see §3' || echo 'Up to date')"
   echo "9. App Key:      $(grep -q '^APP_KEY=base64' .env && echo Set || echo MISSING)"
   echo "10. HTTP /:      $(curl -sI -o /dev/null -w '%{http_code}' https://[PROJECT_NAME].test/)"
   echo "11. HTTP /login: $(curl -sI -o /dev/null -w '%{http_code}' https://[PROJECT_NAME].test/login)"
   # Expected: 1–6 OK/Linked/Present/Connected, 7 ≥ 50, 8 "Up to date", 9 "Set", 10 200/302, 11 200

   • ✅ Every gate line passes (or the failing line maps to a known fix below).

2. Confirm the rendered app in a browser (👤) — log in and check the dashboard, nav, images, and CSS, with no console errors.

   • ✅ The dashboard renders fully after login.

3. Scan the log for anything missed.

   tail -50 storage/logs/laravel.log | grep -i "error\|exception\|fatal" || echo "No errors"
   # Expected: "No errors"

   • ✅ The log tail is clean.

If a gate check fails, the most common fixes: rerun page 1 (1–3), page 3 (4), page 4 (5,7), check .env + Herd DB service (6), php artisan key:generate (9), and the page-3 root-500 note (10).

You’re logged in with DEFAULT credentials

Do not deploy with them. Password and email rotation happens in Phase 6 after SMTP is configured (so reset emails work).

Migration quick-reference

Keep this card handy — it summarizes the rules above

Command	Use
php artisan migrate:status --no-ansi	List ran / pending (always --no-ansi so grep sees Pending)
php artisan migrate --pretend	Preview SQL without running it
php artisan migrate --force	Run pending migrations non-interactively on staging/deploy
php artisan migrate --path=… --force	Run one module/extra migration path

A migration shows “Pending” for one of four reasons: genuinely new; already applied but its row is missing from migrations; a vendor migration the installer handled differently; or a dev-only migration excluded under --no-dev.

Mark an already-applied migration as ran instead of re-running:

CREATE TABLE IF NOT EXISTS _backup_migrations AS SELECT * FROM migrations;
INSERT INTO migrations (migration, batch) VALUES ('2024_..._name', 999);

CodeCanyon do / don’t

• ✅ Edit the database, never vendor migration files.
• ✅ Add Schema::hasTable() / Schema::hasColumn() guards only to your _zaj-suffixed migrations.
• ❌ Never migrate:fresh, migrate:reset, or db:wipe on shared data.
• ❌ Never edit or drop a vendor migration to “fix” a pending row — use the batch-999 mark instead.

Checklist

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

• 🤖 No pending migrations — migrate:status clean, modules counted.
• 🤖 Vendor duplicates resolved — via the migrations table, not file edits.
• 🤖 Baseline written — normalized local.sql; 0 noise lines; CREATE TABLE count matches DB.
• 🤖 11-point gate green — all eleven checks pass.
• 👤 Browser verified — login + dashboard confirmed; laravel.log clean.

→Next step

Commit & secure