Database migrations and CLI

Core migrations

Ordered .sql files in database/migrations/. Tracked in a migrations table so each file runs once.

composer migrate

When to migrate

• After git pull that adds new migration files
• Fresh install on empty database
• Before enabling features that depend on new tables (content lists, entry_refs, commerce digital grants, …)

Plugin migrations

Plugin SQL in plugins/{slug}/migrations/ runs on activation, recorded in cms_plugin_migrations. Core migrator does not scan plugin folders—activation applies them.

CLI entry point

php bin/cms.php

Common subcommands:

• jobs:dispatch — Queue due scheduled jobs
• jobs:work --limit=20 — Process job queue
• Cache and diagnostic tools (vary by build)

Cron setup

*/15 * * * * cd /var/www/struxa && php bin/cms.php jobs:dispatch && php bin/cms.php jobs:work --limit=20

Required for scheduled publish, revision purge, sitemap warm, media compression batches.

Writing migrations

Add new numbered SQL files to database/migrations/. Use idempotent patterns where possible; document destructive changes in commit messages. Never edit applied migration files on deployed sites—add a new migration instead.

Troubleshooting

• Migration halfway failed — Restore DB backup; fix SQL; re-run.
• Plugin table missing — Deactivate and reactivate plugin to replay migrations, or apply SQL manually.