Production
Production-safe migration workflow for Vortos applications.
Production Migration Workflow
Use this order in production deployments:
php vortos migrate:publish
php vortos migrate:status --json
php vortos migrate --force --no-interaction
# Optional: verify schema integrity after deployment (exits non-zero on drift)
php vortos migrate:verifyIf status or migrate reports compatible existing schema:
php vortos migrate:adopt --all-compatible --dry-run
php vortos migrate:adopt --all-compatible --force
php vortos migrate --force --no-interactionIf you have raw SQL user migrations that need adopting:
php vortos migrate:adopt --all-compatible --dry-run
# Review the unverified migrations listed in the output, confirm schema is correct
php vortos migrate:adopt --all-compatible --allow-unverified --force
php vortos migrate --force --no-interactionIf you accidentally adopted a wrong migration:
php vortos migrate:unadopt Version20260505114121 --forceCI Schema Verification
migrate:verify checks every executed framework migration against the live database schema and exits non-zero if any drift is detected. Run it after a deployment as a post-deploy smoke test:
# exits 0 — all executed framework migrations match the live schema
php vortos migrate:verify
# exits 1 — drift found, lists which migrations and what is missing
php vortos migrate:verify
# machine-readable output for CI pipelines
php vortos migrate:verify --jsonOnly framework module migrations are checked — user-authored migrations are skipped because Vortos has no schema definition for them. If drift is detected after a deployment, the output tells you which migration and which tables or columns are missing.
Rules
- Do not run
migrate:freshin production. - Do not use
--no-lockin production. - Do not edit old migration classes after they have shipped.
- Always run
migrate:statusbeforemigratewhen investigating schema problems. - Always run
--dry-runbefore adopting in production. - Run
migrate:verifyas a post-deploy check to catch schema drift early.
Duplicate Table Errors
If you see:
relation "role_permissions" already existsthe likely cause is metadata drift:
table exists physically
but migration is not recorded in vortos_migrationsUse:
php vortos migrate:status
php vortos migrate:adopt Version20260505114121 --verifyDo not drop the table unless this is a disposable local database.