Installation

[dependencies]
amethystate = { version = "0.22", features = ["redb"] }

No engine is built in until one is named. The application names the one that holds its file; a crate that only declares structs, or adapts a framework, names none and leaves the choice to the application. The rest of this page is about which to name.

Choosing an engine

Six engines can hold the store, and exactly one of them holds a given store. Cargo features decide which of the six are built in at all; which one takes the store is said when it is opened, through StoreBuilder::backend. Say nothing and the first one built in takes it.

feature	engine	where it lives
redb	redb	a .redb file
sqlite	SQLite	a .db file
json	JSON	a .json file
toml	TOML	a .toml file
ron	RON	a .ron file
localstorage	the browser’s localStorage	keys under amethystate.<store name>. in the page

The text engines write two files: the data, and a .meta sidecar. The sidecar carries what the store needs in order to read the data back - which version of each struct wrote it, what those fields looked like, and what the migration pass has already done. A person can still read the data file on its own; the store opening it without the sidecar has lost the schema it was written under, so both belong to the store and a backup takes both. redb and SQLite keep the same record inside their single file.

The format sets what the store can express. Choosing an engine measures what each engine does with the same values.

A build with no engine in it still compiles, and a store opened in it is refused: StoreBuilder::build answers OpenStore::WouldNotOpen, naming the features to turn on.

The memory feature adds one more engine, with no file at all. It never takes a store on its own: it is asked for by name, or stands in for a file that will not open - see Opening a store.

In a browser

A page built for wasm32-unknown-unknown has no files, and the localstorage feature is the engine for it: the browser’s localStorage, one JSON value per key, readable in the developer tools. A write lands in the call that makes it, with no debounce, and a full quota comes back as the error of that set. A write another tab makes arrives as a change from outside, the way an edit to a text engine’s file does. Anywhere but a page the open is refused.

amethystate = { version = "0.22", features = ["localstorage"] }

Several engines at once

Engine features are additive, and when more than one is built in, a store that names no engine opens with the first of redb, SQLite, JSON, TOML, RON, localStorage. A dependency that turns on redb somewhere in the tree therefore puts redb in charge of such a store, whatever your own crate asked for.

Compiling several in at once is legitimate - a tool that reads whichever file it is pointed at, or a test suite that runs the same case over each. Name the engine explicitly when the store is built and that order stops mattering.

SQLite

SQLite is built from source, so you need a C toolchain. In exchange the minimum SQLite version is this library’s choice rather than whatever the user’s distribution ships.

That is not cosmetic. Start using some SQLite feature — STRICT tables, say — and the minimum jumps to 3.37. Nothing in the file records that it did, so an older SQLite reports a corrupt schema rather than a version it cannot read, about a file that is perfectly intact.

amethystate = { version = "0.22", features = ["sqlite"] }

Tauri

Tauri integration includes a plugin, async backend, and Rust and TypeScript bindings generator. Enable it with the tauri feature, next to an engine:

amethystate = { version = "0.22", features = ["tauri", "redb"] }

See Tauri integration for setup and usage.

Migrating from an existing solution

See Migrating from a custom solution.

Framework integrations

See Integrations.