Upgrading the server and checking state after a migration

Français · Type: how-to · Audience: admin · Context: hosted Studio · Status: ready · Applies from: 4.2.3

The Studio Server (hosted team Studio) · contract: experimental · verified by CI (support matrix of 4.4.0, 2026-10-23): Postgres, S3 and Keycloak in CI; Chromium and Firefox (job studio-hosted); WebKit on macOS, by hand only · automated checks: jobs studio-hosted, studio-install-smoke; CI plan studioHosted; 3 test files · people's passes: studio-hosted not run (#149), studio-collab not run (#150), studio-preview not run (#166), studio-assets-hosted not run (#167), studio-mcp-remote not run (#196), studio-oidc-generic not run (#197) · known limits: none listed on this page

Upgrading the Studio Server is the same overlapping redeploy as any other, of a new version: the database migrations run when the new instance starts. This page upgrades both apps and checks, afterwards, that the game is where it was.

What you get

Both apps at the new version, the database migrated to its schema, the game's revision unchanged by the upgrade, writes served again, and a backup taken just before, to go back to if needed.

Context and versions

• A hosted Studio on Clever Cloud, deployed from the repository, from 4.2.3 (the lease handoff).
• This page is about the server. The game's own content (authoring schema 2 → 3, the former web-scumm/… imports) is upgraded inside the Studio by its owner: Upgrading the engine of a hosted game.
• Verified on: 19 October 2026, by the reference deployment: an upgrade from commit 52e68932 to c66fbf56 (both package.json 4.2.2, before the 4.2.3 tag), with one new migration (0012, the comments table), following these four steps. This page's exact text is not verified on a live installation.

Prerequisites

• A running Studio with backups (Backups).
• The engine repository on your machine, checked out at the new version, npm ci done.

Where to run the commands

git, clever deploy: on your machine, in the engine repository. The backup: in a shell on the studio app (clever ssh --alias my-game-studio).

Steps

1. Read the version's CHANGELOG, and the upgrade notes for the game's content (Upgrade). List the new database migrations between the two versions:

   # on your machine, in the engine repository
   git diff --name-only v4.3.1 v4.4.0 -- studio-server/migrations
   

   Migrations run when the new instance starts, while the old one may still serve. If one changes what the old version reads (a column it uses renamed or dropped, not a new table), stop the old one first, clever stop --alias my-game-studio, and accept the minute without the Studio.

2. Take a backup to the bucket and note its revision:

   # in a shell on the studio app (clever ssh --alias my-game-studio)
   cd "$APP_HOME" && npm run -s studio-server -- backup --to-bucket
   

3. Deploy the worker first, then the studio, the same version:

   # on your machine, in the engine repository, at the new version
   clever deploy --alias my-game-worker
   clever deploy --alias my-game-studio
   

   Until both are at the new version, a job may be refused; the Studio then refuses the write it was checking (it fails closed, a 503) rather than letting it through.

4. Watch /readyz come back to 200 on the new instance (instance in the lease-taken log line), check the revision is unchanged, and make one write.

Measure · upgrade-run The studio deploy with migration 0012: "1 minute and 29 seconds". The revision went on: 52 before the switch, 53 for the first write after it; later writes answered in 164 to 600 ms. Writes were refused for 2 min 23 s (this version had no lease handoff yet; Redeploys), and one write, retried 70 times with its id, was applied once.

• date: 2026-10-19
• version: 4.2.2
• volume: the demo game, revision 52; one new migration
• conditions: reference deployment phase B, 52e68932 → c66fbf56 on main before the 4.2.3 tag (package.json said 4.2.2); worker then studio, XS apps, PostgreSQL DEV, region par
• source: QUALIF-4.2.3-REFERENCE.md §1 and §5

Expected result, and how to check it

Check, in this order:

• It started. The new instance's log has {"event":"lease-taken",…}; https://studio.example.fr/readyz answers 200, "writes":"served", rpoMs back to 0.
• The game did not move. As a member, GET /api/revision gives the same epoch and revision as before the deploy (or later, if people wrote meanwhile).
• It writes. One change (a note) is saved, at the next revision.
• The schema. With psql and the add-on's URI (Clever's console shows it; never paste it anywhere), SELECT MAX(version) FROM schema_migrations gives the number of the newest file in studio-server/migrations/ of the new version.
• The worker. The header's health goes green again and a preview builds (the worker's jobs succeed); in the logs, no health-failed or preview-failed after the switch.
• A restore still works. Run the restore drill with the new version, on a backup taken after the upgrade.

Common errors

Files or data changed

The database schema (new migrations applied, recorded in schema_migrations), a new backup under backups/, the two apps' deployed commit.

Recovery or going back

Redeploying the previous version works only while it can still read the migrated database; an older server refuses a database whose schema is newer than its own. Otherwise, going back is restoring the backup of step 2 into a new add-on, with the previous version: Limits of going back.

References

• The migrations: studio-server/migrations/ (one NNNN.up.sql and NNNN.down.sql per step); the runner: bridge/src/migrations.ts.
• Redeploys, Backups, CHANGELOG.md.

Edit the source of this page · Report an error