Compatibility

LuraDB is 0.x software: on-disk formats and the REST API can change between minor releases. GET /version reports the server version and the version of the API contract. LuraDB runs on Linux amd64 with kernel 6.1 or newer.

What 0.x means

Before 1.0 the project makes no promise that a newer release reads the data or speaks the API of an older one. What it does promise is that changes are announced. Every release in the changelog lists what changed, and two markers say where to look: API: for an entry that touches the REST API, and BREAKING for a change that can make an existing client, configuration or data directory stop working. Read every release between the one you run and the one you install, and take a backup first when a release changes the format on disk.

The server version and the version of the API contract are numbered independently of each other.

The API contract version

The REST API has a contract, the OpenAPI document that the server serves and prints, and the contract has a version of its own. GET /version returns both numbers for any valid key:

curl -s http://127.0.0.1:3000/version -H "Authorization: Bearer $KEY"

{ "server_version": "0.5.1", "api_version": "0.14.2" }

api_version has the form major.minor.patch. The rule of the code is that a breaking change bumps the middle number and anything else the last. A client that was written against 0.14.x can therefore expect a server with the same middle number to answer as the contract says, and should look at the changelog when the middle number is higher. The same version is the info.version of the OpenAPI document, and the server version is in its x-luradb-server-version extension:

luradb --dump-openapi | jq -c '.info | {title, version, server: .["x-luradb-server-version"]}'

{"title":"LuraDB API","version":"0.14.2","server":"0.5.1"}

A client can ask GET /version once after it connects and refuse to go on when the middle number is not the one it knows. The request needs a key but no permission on a domain.

What 0.5.1 changed for API clients

The release 0.5.1 changed the behaviour of the API in the places below, all marked BREAKING in the changelog. If your clients were written against 0.4.0, check these.

Area	Change
Key-value writes	Keys carry an ETag. PUT, DELETE and PATCH …/null accept If-Match and If-None-Match: * and answer 412 when the precondition fails.
Strict domains	A domain created with require_conditional_writes answers 428 to an unconditional single-key write.
JSON documents, failed If-Match	412 instead of 409, also for a missing document, and every 412 carries the ETag of the current version. If-Match can be combined with If-None-Match: *. See Consistency.
Overload	503 with Retry-After: 1 when the queue of a shard or the reader pool is full.
Disk or memory shortage	Writes answer 507 with Retry-After: 5 instead of 500; reads go on. See Resource guard.
GET /health	Reports the status of each shard and answers 503 with "status": "degraded" when a shard does not respond. It has the fields resources and io.
GET /store-api/metrics	Answers 503 while a data shard is not running. It has the new blocks shm and resources.
Connections	Requests on one connection are processed in order, HTTP/2 included; a connection serves one stream at a time. Use several connections for parallelism.
Watch and event streams	The ids carry the shard in their epoch; existing cursors resync once after the upgrade.
Backups	Relational domains are included, the scope accepts rel and rel:<domain>, and the archive has manifest format version 2. Archives of format version 1 still restore.
Domain listings	A user gets the domains its key has a permission on instead of 403. Details of a JSON or relational domain are readable with a permission on it.
POST /store-api/domains with an invalid name	400 instead of 500.
GET /store-api/config	No longer reports the removed configuration keys.

What an update does to the data

Updating the package does not touch the data directory; the first start of the new binary does. In 0.5.1 that start changes the format of the directory, once and in one direction:

Change	Effect
The write-ahead log path becomes a directory of 64 MiB segments, and the header records the starting sequence number.	A log file of an earlier version at the path is converted on the first start. An earlier version cannot open the directory afterwards.
The engine files move into a shard_0/ directory beside the configured paths.	The first start moves them with rename. Data written without shard directories counts as one shard, so a start that asks for more shards is refused with shard count changed (stored 1, configured N) — run `luradb --migrate-shards N`, see Upgrading.
Users, key hashes and permissions move into the system store, storage.system_dir.	Copied on the first start, then deleted from the key-value engine.

To go back to an earlier version, restore a backup taken before the update into that version; the data directory itself cannot be opened by it. The changelog lists the earlier formats: version 0.2.0 made stores of 0.1.1 and earlier incompatible, so that they had to be rebuilt, and the entries for 0.3.0 to 0.4.0 name no change of the format on disk.

Configuration changes with the release too. 0.5.1 removed 72 tuning keys and fixed their values; a luradb.toml that still sets one starts, warns and ignores it, see the removed keys. Two defaults changed in 0.4.0 and matter to an upgrade from before: server.bind_address became 127.0.0.1 (it was 0.0.0.0), and server.swagger_enabled became false, with the Swagger UI and the OpenAPI document requiring a key while authentication is on.

Backup archives

An archive carries its own format_version in the manifest, together with the luradb_version that wrote it. The format version is 2 since 0.5.1; version 1, written by earlier releases, has no shard count, no log position and no relational data. This server restores archives of the versions 1 and 2; any other version answers 400 Bad Request: unsupported backup format version. An archive restores into any shard count. Because it lists what the domains hold and not how a release stores it, an archive is the form that crosses the changes of the data format above.

Platform

Requirement	Value
Operating system and architecture	Linux on amd64. The Debian package is built for amd64.
Kernel	6.1 or newer. The server sets up io_uring rings with DEFER_TASKRUN and refuses to start on an older kernel with LuraDB requires Linux kernel 6.1 or newer (io_uring DEFER_TASKRUN).
C library	glibc 2.34 or newer (libc6 (>= 2.34) in the package).
Service manager	systemd, if you install the package. A Docker container and a build from source do not need it.
Other packages	adduser, which the package uses to create the luradb user.
Docker	A host, or the virtual machine of Docker Desktop, with a kernel of 6.1 or newer; the container runs with seccomp=unconfined and an unlimited memlock, see systemd and Docker.
Build from source	The Rust toolchain pinned in rust-toolchain.toml.

LuraDB needs Linux. On Windows or macOS, run it in Docker, where the Linux kernel of the container host must be 6.1 or newer.

Related settings storage.system_dir · multicore.shards · server.bind_address ·

server.swagger_enabled