Skip to content
NexusFabric

Versions and compatibility

Four different numbers in this product are called a version, and they change for different reasons. This page says what each one names, what survives an upgrade, and how to move an installation forward or back.

The four numbers

Number Where it lives What it names
The release nexus --version, the changelog The build of the platform you are running: binary, migrations, manual
The language version flowmarkdown_version: in a flow file Which version of FlowMarkdown the file is written against. Required; "0.0" and "0.1" are accepted
The artifact version nexus deploy --version 1.3.0 Your name for one published revision of one flow, in one tenant
The artifact hash printed by deploy, shown in the Registry page The identity of the compiled bytes themselves, computed from them

Only the first is ours. The artifact version is a label you choose: the platform stores it, refuses to let you claim it twice for the same flow, and never interprets it — 1.3.0 does not resolve before or after 1.2.9, because the flow that runs is the one latest points at, not the highest number. See Running NexusFabric for how latest resolves on each door.

The hash is the one identity nobody chooses. It is computed over the artifact’s own bytes and verified on every read, so a stored artifact that no longer matches its key fails the request instead of executing something that changed underneath you.

Publishing a new revision of a flow

nexus deploy compiles the file, stores the artifact and moves that flow’s latest pointer. It runs against a live server: every request resolves latest when it arrives, so the next one uses the new artifact and the requests already in flight finish against the one they started with. No restart, no drain, with one exception — a change to schedule: is read at startup.

A version number is claimed once. Redeploying the same number fails and changes nothing, which is what makes a version a fixed point you can cite in a ticket. Older versions are never deleted: their bytes stay in the registry and the Registry page lists them.

Going back is a deploy, not a delete. Publish the previous source again under a new number; that moves latest back to equivalent bytes and leaves the history intact.

What an upgrade of the platform does

Artifacts published by an earlier build keep running. The compiled artifact is the contract between the two, and an upgrade does not rewrite it. This has a consequence worth stating plainly, because it cuts both ways: a check added to the compiler applies at publication, so a flow that was published before the check keeps running exactly as it did. To get the new verdict on an old flow, republish it — nexus validate gives the same answer without side effects.

A few of those checks matter enough that the platform says so at startup rather than waiting for a republish, naming the tenant, the flow and the key at fault. Where that happens it is documented on the page for the feature, and the repair is always the same: fix the file and deploy it again.

The databases migrate forward on their own. Each schema change is a numbered migration, applied once, in order, inside its own transaction, and recorded in the schema_migrations table of the database it belongs to. Starting a newer build against an older database applies whatever is missing, and starting it twice applies nothing the second time.

There is no down migration. A database that has been migrated forward is not readable by the previous build, so going back to an earlier release means restoring the state directory from the snapshot taken before the upgrade. That is the order for any upgrade worth planning:

  1. Stop the engine, or all of them.
  2. Copy the state directory — registry, queue, log and UI databases, and the queue directory beside them. Running NexusFabric lists what is where.
  3. Put the new binary in place and start one engine. The migrations run at startup, and a failure stops the start rather than half-applying.
  4. Check /health, then the Dashboard, then send one message through a flow you know.
  5. Start the rest.

What counts as a breaking change

A release note names a change as breaking when it can change the behaviour of something already published or already integrated against. In practice that is one of:

  • the meaning or the name of a frontmatter or step key;
  • the shape of a response body, or the status code an outcome produces;
  • a name the platform reserves for itself;
  • a new refusal at publication, which is breaking for the next deploy of an existing file rather than for the running installation;
  • a schema migration that cannot be reversed, which is every one of them.

Each of those appears in the changelog for the release that carries it, with the repair next to it. The manual is updated in the same change that ships the behaviour, so the page you are reading describes the build you are running, not the one before it.

Licence

NexusFabric is commercial software, licensed per contract. There is no public download and no source distribution: the binary, the image and the accompanying documentation reach a customer through the agreement signed with them, and the terms of that agreement — not this page — govern the installation.

For the versions supported under a given agreement, and for what an upgrade entitlement covers, read the contract or ask your contact at TECHNOHUB SRL.