Which version of Console works with which server, what the warning banner means, and how Setup keeps them in step.

The four numbers

Open Settings -> Versions to see all of them for the server you're connected to.

Number What it is Where it comes from
Console The version of this desktop app Built into the app
Api The version of the server's Api Reported by the Api each time it starts
Worker The version of the server's Worker Reported by the Worker each time it starts
Database schema A whole number for the shape of the database Written by Setup when it deploys or upgrades the database

The server also tells Console which range of Console versions it supports (for example, 0.1.0 to 0.1.999). That range is the real compatibility rule. It is a range, not just a minimum, for two reasons:

  • A Console that is too old asks for things the server has removed or changed.
  • A Console that is too new asks for things the server (or its database) doesn't have yet. This is the one people trip over after installing a newer Console against a server nobody upgraded.

A release that only fixes bugs stays inside the range, so older and newer Consoles keep working. A release that changes the database or the Api moves the range.

The warning banner

When this Console and the server don't line up, a banner appears across the top of the app. It goes away on its own when they do. It can say:

Banner says What's wrong What to do
Console is older than this server supports The server moved on without this Console Install the newer Console (run Setup and tick Console)
Console is newer than this server supports This Console expects features the server doesn't have Run Setup's Upgrade on the server
Database schema is older than this server expects The database wasn't upgraded along with the Api Run Setup's Upgrade on the server
Database schema is newer than this server expects The database is ahead of the Api and Worker Update the Api and Worker (Setup's Upgrade)
Database has no schema version yet The database predates version tracking Run Setup's Upgrade on the server
Server predates version tracking An old Api with no version information Run Setup's Upgrade on the server

The Versions button on the banner jumps straight to the details.

How Setup keeps them together

  • On an upgrade, Setup now shows the Components step. Api, Worker and Console are pre-ticked from what is actually installed on that computer, with each one's installed version next to the version being installed. Untick anything you don't want touched.
  • If the installed Console is outside what the new server supports, Setup requires the Console upgrade. The Console box is ticked and locked, with a note saying why. Upgrading the server alone would leave a Console that fails against it.
  • Setup also upgrades the database itself, including columns and seed rows added after the database was first created, and records the new schema version.

Situations

You are... Do this
Upgrading the server Run Setup, choose Upgrade, leave Console ticked (it will be required if it has to move)
Updating only your own desktop app Run Setup on your computer and tick only Console. Check Settings -> Versions afterward
Connected to a server and see the banner Read the sentence in the banner; the fix is the one in the table above
Running several fleets, one older Each fleet reports its own range. Switching fleets (top bar) re-checks, so the banner can appear for one and not another
Unsure which version is where Settings -> Versions lists Console, Api, Worker and schema together, and when the Worker last reported

For whoever ships a release

There is one source of truth, Versioning\ReleaseCompatibility.cs, shared by the Api, Console and Setup:

  • Bug-fix release: change nothing there. The version number moves; the range already covers it.
  • Release that changes the schema: raise ExpectedSchemaVersion and the matching number in Script.PostDeployment.sql, and add a guarded block to the installer's SchemaCatchUp.sql.
  • Release whose Console needs the new server: raise MaxConsoleVersion to the new Console version in the same release.
  • Release that removes something older Consoles use: raise MinConsoleVersion.

tools\check-installer-script-drift.js fails if the schema numbers disagree or if the installer's copy of the database scripts falls behind.

See also: Connecting Console to Your Fleet and Glossary.