Migrations and upgrades

Spectron bundles schema migrations into the binary and applies them automatically. This page explains how migrations work and what to expect during version upgrades.

How migrations work

Each Context database is created from schema bundled into the server binary. Migrations are append-only — applied automatically on context creation and on server startup. Applied versions are tracked in each Context database.

Most upgrades are additive (new tables, fields, indexes). A minority include destructive steps (dropping retired tables or fields). Always take a SurrealDB backup before upgrading production Contexts.

After upgrades that change scope semantics, audit clients that pass multi-path flat arrays: ["a", "b"] is now OR, not AND — use [["a", "b"]] for conjunction.

Downgrading after a destructive migration is not supported — the older binary may not start against the new schema.

Upgrading Spectron

Rolling upgrades

Spectron is a horizontally scalable application server – all durable state lives in SurrealDB. A rolling upgrade works as follows:

1. Deploy the new Spectron binary (or container image) alongside the running version.

2. The new version starts up and applies any pending migrations to all registered Contexts.

3. Route traffic to the new version.

4. Shut down the old version.

Because replicas do not cache durable state in-process, you do not need to drain in-flight requests beyond what your load balancer already provides. In-flight document processing jobs are stored in SurrealDB and will be picked up by workers on the new version.

Single-instance upgrades

For single-server deployments:

1. Take a SurrealDB backup of all Context databases (see Backups and retention).

2. Stop the Spectron service.

3. Replace the binary or pull the new container image.

4. Start the service and watch logs for migration completion.

5. Run smoke tests against a non-production Context before routing production traffic.

Verifying migration success

After upgrade, check server logs for migration completion. If a migration fails, Spectron logs the error and refuses to serve requests for the affected Context until the schema is consistent.

Version compatibility

Always upgrade SurrealDB and Spectron together according to the release notes for your distribution.

After additive migrations, an older Spectron version may continue to run against a newer schema — it simply ignores tables and fields it does not know about. That does not apply once a destructive migration has run.

Docker upgrade

docker pull ghcr.io/surrealdb/spectron:latest
docker compose down
docker compose up -d
docker compose logs spectron | grep -i migration

Kubernetes upgrade

Update the image tag in your deployment manifest, then roll out:

kubectl set image deployment/spectron \
  spectron=ghcr.io/surrealdb/spectron:latest
kubectl rollout status deployment/spectron

Each new pod applies pending migrations on startup before serving traffic.

Bare metal / systemd upgrade

Replace the spectrond binary (see Bare metal), then restart the service:

sudo systemctl restart spectrond
journalctl -u spectrond -f

Downgrading

Downgrade only when no destructive migration has been applied since your backup. If the newer version dropped or reshaped tables, run the restore workflow in Backups and retention rather than starting an older binary against the live database.

Backup before major upgrades

Before upgrading, take a SurrealDB backup of each Context database:

surreal export \
  --conn ws://localhost:8000 \
  --user root --pass secret \
  --ns acme --db prod \
  pre-upgrade-backup-$(date +%Y%m%d).surql

Store the backup externally. The full backup and restore workflow is in Backups and retention.