Compatibility and versioning

There are four version questions here and they are independent of one another, which is why "what version of Strata are you on" is rarely enough to answer a compatibility problem. The binary, the on-disk format, the SDK and the interface each move on their own schedule.

Strata is a research preview. That makes this page more important rather than less: instability is tolerable when you are told where it lives.

The current set

Engine and CLI are at 1.2.7, carrying 139 commands, built for 6 platform targets. Those numbers come from the release this site was built against, not from a list kept by hand.

Can this binary open this database?

The on-disk format has its own version, and it is not the same number as the binary. The database format is 1. The manifest that describes it has its own version, raised to 3 in 1.2.6.

1.2.6 upgrades the manifest the first time it opens a database for writing. It reads both the old manifest and the new one, so your existing databases open without a migration step. But it writes the new one, and 1.2.5 only accepts the old one, so once 1.2.6 has written to a database,1.2.5 will not open it again. The upgrade is one-way and it happens on first writable open, not on a command you run deliberately. A read-only open does not trigger it.

1.2.7 changes no format: it and 1.2.6 read each other's databases, and upgrading between them is not a one-way step. What 1.2.7 does do on its first open of a 1.2.6 database is clean up storage 1.2.6 left behind (strata-core issue 3692), which changes the directory's size but not what it holds.

If you need to keep a database readable by 1.2.5, copy it before letting 1.2.6 write to it. A 1.2.5 binary meeting an upgraded database reports failed_precondition.engine.format_version, which is the same refusal any binary gives a format from the future.

A binary that meets a format it does not understand refuses it rather than guessing. A database written by some future format is rejected as a future format, naming the highest version this binary supports. A pre-1.0 development database is rejected as well, deliberately and by a distinct path, so an old experiment cannot be silently half-read. The manifest carries a magic marker and a CRC, so a truncated or corrupted one is caught at open rather than surfacing later as wrong data.

That is the forward-compatibility answer, and it is the conservative one: an older binary will not open a newer database, and will say so. There is no partial read.

Does this SDK match this engine?

The Python SDK is at 1.2.4 and the engine is at 1.2.7. They are published separately and this window happens after most releases. The SDK talks to the engine it is loaded against, so the practical effect is that commands added in 1.2.7 may have no Python method yet.

6 of the 139 commands have no Python method today. Every command page in the reference shows the Python spelling when one exists and says so when it does not, generated from the installed wheel rather than written down.

Two processes, two versions

One case is worth knowing before you hit it. When a process brokers to a host, the two negotiate on a protocol revision, and the pairing is not refused when their releases differ. Between 1.2.1 and 1.2.2 the revision is the same number on both sides, so the connection is accepted, and one specific read fails at the point of use rather than at connect: a 1.2.2 client reading a historical JSON value from a 1.2.1 host cannot decode the answer.

The reverse direction is fine. An older client reading from a newer host works, because the shape it already knew is still there.

So: run the same version on both sides of a broker. This is tracked upstream as strata-core issue 3369. A related one is worth pairing with it, strata-core issue 3395: a client that asks for--durability always against a host running the default gets the host's mode, and the flag is accepted silently. Durability covers what that costs.

What a research preview promises

Plainly: the command surface is still moving. Commands have been added and renamed between minor releases, output formats changed shape in 1.2.2, and a capability enum was renamed in the same release. None of that is finished.

What is stable enough to build on:

• The error codes. Stable identifiers with a retry policy and a commit outcome per code, which is what a program should branch on. See Error codes.
• The --json envelope. It did not change when the human output was rewritten in 1.2.2. It is the format to parse.
• Format 1 on disk. Unchanged across every 1.x release so far.

What is not:

• The human output. It is for reading, and 1.2.2 rewrote it wholesale.
• Command names and flags, which are still being added to.
• Node.js and Rust, which do not ship.

Upgrading

strata update replaces the binary in place. Because every 1.x release reads format 1, there is no migration step and no downgrade hazard within 1.x today. Back up first anyway if the data matters: Databases and storage covers what is safe to copy and when.