Versioning
Dynoxide has two version numbers, and they are different on purpose.
The product version covers everything you install: the dynoxide CLI and its platform binaries, the npm packages, the browser engine, the container images, the GitHub Action and the Homebrew formula. dynoxide --version reports it, and so do the x-dynoxide-version and Server headers and the MCP server info.
The crate version covers dynoxide-rs on crates.io, and nothing else.
They were one number until 1.1.0. The split happened because a change to a public Rust type would otherwise have forced a major version on every artefact whose users never touch the Rust API, and moving everyone to ^2.x and dynoxide:2 to report a change they cannot observe is a poor trade.
Right now that means product 1.6.0, crate 3.3.0.
Which number do I want?
| If you are | Use |
|---|---|
Running npx dynoxide, Docker, Homebrew or the GitHub Action |
Product version |
Reading dynoxide --version output, or filing a bug report |
Product version |
Adding dynoxide-rs to a Cargo.toml |
Crate version |
Running cargo install dynoxide-rs --version X |
Crate version |
cargo install dynoxide-rs --version 1.6.0 will not find anything, because 1.6.0 is a product version. The Embedded SDK page renders its pin from crates.io, so copy it from there.
What moves which
A release can move one stream and leave the other alone. A Rust-only break publishes a new crate against an unchanged product; a CLI-only change publishes a new product against an unchanged crate.
| Change | Stream | Bump |
|---|---|---|
| Breaking change to a public Rust type or signature | Crate | major |
| Public Rust type or function added | Crate | minor |
| New feature flag, or an MSRV raise | Crate | minor |
| Feature flag turns on less, with no public item lost | Crate | minor |
| CLI flag removed or renamed | Product | major |
| HTTP response shape or error string change | Product | major |
| Container entrypoint or exposed port change | Product | major |
| Startup line text, or the stream it goes to | Product | major |
| Engine behaviour change | Both | major, unless it is a capture-backed conformance fix |
| Capture-backed conformance fix | Both | minor |
| Browser client API or Worker protocol change | Product | major |
| New DynamoDB operation | Both | minor |
The MCP surface carries no version promise of its own. The data model is context for an agent rather than something the engine enforces, so serverInfo.version reports the product version, which is what you installed.
Upgrading to product 1.6.0 and crate 3.3.0
The crate takes a minor for the new types::READ_UNIT_BYTES constant and loses no public item; the crate 3.3.0 notes have the detail. The product takes a minor because PartiQL reads, request validation and number handling move closer to DynamoDB, so some requests answer differently and some that used to be accepted are refused. The compatibility notes list what tests are likely to notice. The database schema stays at 11.
To hold behaviour across minor releases, use a patch-only npm range such as ~1.6.0, a container minor tag such as dynoxide:1.6, or an exact crate version and your Cargo lockfile. These are pinning examples for the 1.6.0 release, rather than the site's current registry versions.
Upgrading to product 1.5.0 and crate 3.2.0
The crate takes a minor because the http-server and mcp-server features stop turning on cli, which loses no public item; the crate 3.2.0 notes say which builds notice. The product takes a minor because the release brings read capacity, stream records and SearchVectors errors in line with DynamoDB, so some requests answer differently. The compatibility notes list what tests are likely to notice.
A stream SequenceNumber from an earlier build is refused, so a consumer holding one has to restart from TRIM_HORIZON after the upgrade. Going back to 1.4.x has no refusal: a number saved under 1.5.0 doesn't resolve there, so the consumer quietly reads the stream again from its start. See stream records. The database schema stays at 11.
Upgrading to product 1.4.0 and crate 3.1.0
The crate takes a minor for the new server::serve_with_shutdown. The product takes a minor because most of the release brings answers in line with captured DynamoDB behaviour, mainly update expressions and Scan and Query validation, so a request 1.3.0 accepted may now be refused. The compatibility notes list what tests are likely to notice, and the crate 3.1.0 notes cover requests built in Rust.
The database schema stays at 11, so coming from 1.3.0 there is no file upgrade. Coming from 1.2.x, the 1.3.0 notes below still apply.
Upgrading to product 1.3.0 and crate 3.0.0
The crate takes a major because public Rust parsers become private and request types and a capacity signature change. The product takes a minor under the capture-backed conformance rule. A test that relied on an older divergence can still fail after a minor update; semver doesn't freeze the emulator's answers.
Read the crate migration guide before updating a Rust dependency. Product 1.3.0 upgrades files to schema 11. Keep a copy before upgrading if your file has a multi-attribute GSI or a vector index and you may return to 1.2.x. Files without either still read correctly in 1.2.x. The storage guide covers native, encrypted and browser databases.
Prereleases
Prereleases reach only the channels that name them. npm publishes them to next; GitHub flags the release as a prerelease; containers get the exact tag. The GitHub Action's default latest, Homebrew and the MCP registry stay on the stable release. A stable crate version waits for the stable product release before it is published.
This site reads npm's latest and crates.io's stable version. A prerelease should not move the install pins or be presented as the latest stable release.
For the full rules, including how each contract is defined, see docs/versioning.md in the engine repository.