Upgrading

Upgrading Statalog to a new version is straightforward. All releases aim to be backward-compatible, and ClickHouse schema changes are always additive — no destructive migrations.

Before you upgrade

Read the release notes. Check the GitHub releases page for the version you are upgrading to. Look for any notes marked "Breaking change" or "Migration notes". These are rare, but important to review.

Back up your MySQL database. Run a full dump before upgrading:

mysqldump -u statalog -p statalog > /var/backups/statalog-$(date +%Y%m%d).sql

ClickHouse data does not require a separate backup step for a routine upgrade — ClickHouse migrations are additive and never drop or alter existing columns. However, if you maintain ClickHouse backups via clickhouse-backup or another tool, running one before upgrading is a good habit.

Upgrade steps

Run these commands from your Statalog installation directory:

# 1. Pull the latest code
git pull origin main

# 2. Install updated PHP dependencies
composer install --no-dev --optimize-autoloader

# 3. Run MySQL migrations
php artisan migrate --force

# 4. Run ClickHouse migrations (safe to run — additive only)
php artisan clickhouse:migrate

# 5. Clear all cached config, routes, views, and compiled classes
php artisan optimize:clear

# 6. Restart queue workers so they pick up new code
php artisan queue:restart

After queue:restart, Supervisor will automatically start fresh worker processes. Existing workers finish their current job before shutting down, so no jobs are dropped.

Zero-downtime tip

If you need to avoid any downtime during the upgrade, run the migrations before switching traffic to the new code. Since ClickHouse migrations are additive, the new columns are ignored by the old code. MySQL migrations follow the same principle in Statalog — columns are added, not removed, in non-major releases.

The sequence for zero-downtime:

  1. Deploy new code to a staging path
  2. Run migrations against production databases from the staging path
  3. Switch your web server or load balancer to serve from the new path
  4. Restart queue workers

Re-caching for production

After upgrading, re-generate the production caches:

php artisan config:cache
php artisan route:cache
php artisan view:cache

ClickHouse schema changes

ClickHouse migrations in Statalog only ever add new tables or new nullable columns to existing tables. They never rename, drop, or change the type of existing columns. This means:

  • Rolling back application code after a migration is safe — old code simply ignores new columns
  • Running clickhouse:migrate on an already up-to-date installation does nothing

If a future major release requires a destructive ClickHouse migration, the release notes will include explicit instructions and a data export step.

Verifying the upgrade

After upgrading, visit your dashboard and confirm that data is displaying correctly. Check the queue worker status with supervisorctl status statalog-worker:* to ensure workers restarted successfully. If you see errors in /var/log/statalog-worker.log, check the release notes for any required .env changes.