Installation

npm

Run a local server without installing anything - the same shape as npx dynalite, if that's what you're replacing:

npx dynoxide

Or install it into a project to pin the version, after which npx dynoxide uses that copy:

npm install --save-dev dynoxide

The package ships platform-specific binaries (the same approach as esbuild and Biome), so there's nothing to compile. It pulls the right binary for your OS at install time.

Homebrew (macOS and Linux)

The quickest way on a Mac:

brew install nubo-db/tap/dynoxide

Homebrew 6.0.0 added tap trust. The fully-qualified command above still installs fine (Homebrew trusts a named formula at install time), but the tap stays untrusted after that, so brew upgrade will skip Dynoxide and brew doctor will flag the tap. Trust it once:

# Trust just Dynoxide - lets brew upgrade see it again
brew trust --formula nubo-db/tap/dynoxide

# Or trust the whole tap - also clears the brew doctor warning
brew trust nubo-db/tap

Cargo

Building from Cargo (crate 3.1.0) needs Rust 1.88 or later:

cargo install dynoxide-rs

For the encrypted build (SQLCipher + OpenSSL):

cargo install dynoxide-rs --no-default-features --features encrypted-full

Pre-built binaries

Grab a binary from the GitHub releases page. Builds are available for Linux (x86_64, aarch64, musl), macOS (Intel and Apple Silicon), and Windows.

curl -fsSL https://github.com/nubo-db/dynoxide/releases/latest/download/dynoxide-x86_64-unknown-linux-musl.tar.gz | tar xz

Docker

If your test suite already runs amazon/dynamodb-local in a container, the official image serves the same DynamoDB API from a small static binary:

docker run --rm -p 8000:8000 ghcr.io/nubo-db/dynoxide

It's multi-arch (linux/amd64 and linux/arm64), built FROM scratch, and ships a HEALTHCHECK, so docker ps and Compose health gates report status without extra tooling. The canonical image is ghcr.io/nubo-db/dynoxide, with best-effort mirrors on Docker Hub (docker.io/nubodb/dynoxide) and ECR Public (public.ecr.aws/nubo-db/dynoxide). Note the Docker Hub namespace has no hyphen where the other two do.

It's a packaging convenience for test fixtures, not a containerised database to run in production. You don't need Docker to use Dynoxide - the native binary needs nothing - but if your pipeline is built around a container, this swaps in cleanly.

GitHub Actions

For CI pipelines, there's a dedicated action. It lives in the action/ subdirectory of the repo, so reference it with that path and pin it to a release tag:

- uses: nubo-db/dynoxide/action@v1.4.0
  with:
    port: 8000

You can also pre-load a database snapshot:

- uses: nubo-db/dynoxide/action@v1.4.0
  with:
    snapshot-url: https://example.com/test-data.db.zst
    port: 8000

See action/action.yml for every input and output.

Upgrading to 1.4.0

The crate is 3.1.0; the CLI, npm packages and containers carry product version 1.4.0. The database schema stays at 11, so a file 1.3.0 has already opened needs no further upgrade. If you are coming from 1.2.x, read the 1.3.0 notes below as well.

Update expressions and Scan and Query validation move closer to captured DynamoDB behaviour, so a request 1.3.0 accepted may now be refused. The compatibility notes cover what tests are likely to notice, and the changelog lists the individual cases.

Upgrading to 1.3.0

The crate is 3.0.0; the CLI, npm packages and containers carry product version 1.3.0. Installing or embedding it needs Rust 1.88. Only running the test suite needs 1.94.1. The SDK guide covers the public Rust API changes.

Opening a persistent file upgrades it to schema version 11. Keep a copy first if the file has a multi-attribute GSI (more than one partition or sort key attribute) or a vector index and you may return to 1.2.x. Those index entries or stored sizes change, and 1.2.x would read them wrongly. Files without either still read correctly in 1.2.x. See database upgrades.

Validation, PartiQL pagination, legacy filters and transaction failures also change to match captured DynamoDB behaviour. A request 1.2.1 accepted may now be refused, so tests relying on the old behaviour may need updating. The changelog lists the individual cases.

Verify it works

After installing, run:

dynoxide

You should see Dynoxide listening on http://127.0.0.1:8000. That line goes to stderr, so a log-based wait in CI needs to watch that stream rather than stdout. --log quiet suppresses that line, so use dynoxide healthcheck or poll GET / when starting a quiet server in CI.