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.

Steps at a glance:

1. Check migration status — Start with the cheap top-level check.
2. Verify the migration count — modules included — Apps using nwidart/laravel-modules often hide migrations inside individual module directories.
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.
4. Capture a normalized schema baseline — A schema baseline turns future drift into a readable diff. Create the structure and export schema-only.
5. Run the 11-point gate — This one-liner proves the app is genuinely functional before any commit or deploy — then browser automation confirms the rendered UI when available.

Agent part + done-when

🔀 User + Agent part — drive public browser checks in a separate browser instance when Playwright/Browser MCP is available or loadable. For login/dashboard verification, the human performs the one sign-in; the agent resumes after the session exists and checks dashboard, nav, assets, console, and logs.

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 human sign-in + agent post-session dashboard check passes with a clean log.  ·  ⏱ ~20–35 min  ·  🔀 mixed (🤖 verification + baseline + post-session browser automation, 👤 login).

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)
DEPLOY_TARGET="<selected-nonproduction-deploy-target>" # from Zaj-PROJECT.md
DEPLOY_PATH="~/domains/<DOMAIN>/deploy"
SSH_ALIAS="<non-production-ssh-alias-from-Zaj-PROJECT>"
ssh "$SSH_ALIAS" "ls $DEPLOY_PATH/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
ssh "$SSH_ALIAS" "cd $DEPLOY_PATH/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
   ssh "$SSH_ALIAS" '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/6-Schema/{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/6-Schema/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/6-Schema/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/6-Schema/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/6-Schema/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 Zaj-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 browser automation confirms the rendered UI when available.

Who does this

🔀 User login, agent post-session verification — if Playwright/Browser MCP is loaded or loadable via ToolSearch, the agent uses a separate/isolated browser instance to navigate to login and snapshot the public form. 👤 User performs the one sign-in transaction. After the authenticated session exists, 🤖 Agent waits for dashboard text, snapshots, and checks console/log output. 👤 User is fallback only when no browser automation exists after sign-in.

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 — the human logs in once, then the agent checks the dashboard, nav, images, and CSS with no console errors. Use an isolated browser instance so the user’s tab is not disturbed.

   browser_navigate https://[PROJECT_NAME].test/login
   browser_snapshot
   # Expected: login form renders
   
   # 👤 Human signs in here; agent does not type credentials or submit the auth form.
   browser_wait_for dashboard text or dashboard URL
   browser_snapshot
   browser_console_messages
   # Expected: dashboard renders; navigation, CSS, and images are visible; no console errors

   • ✅ The dashboard renders fully after login. If the browser hits HTTP 500, tail storage/logs/laravel.log before guessing.

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 — human sign-in + agent dashboard check confirmed via Playwright/Browser MCP when available; laravel.log clean.

→Next step

Commit & secure