Upgrading

Updating LuraDB means installing the newer .deb package over the old one. LuraDB is 0.x software: on-disk formats and the REST API can change between minor releases, so read the changelog before you update. Entries that touch the REST API are marked API:, breaking changes are marked BREAKING.

An update installs the new package over the old one

sudo apt install ./luradb_<new version>-1_amd64.deb

apt replaces the binary and the systemd unit. For the same package version, which apt install treats as nothing to do, use sudo apt reinstall ./luradb_*.deb.

• /etc/luradb/luradb.toml is a dpkg conffile and stays as you left it. When you changed the file and the new package carries a different one, dpkg asks which to keep.
• The admin key stays. The package writes a key only while the file still holds @GENERATED_ON_INSTALL@, which is the case on the first install only.
• The package leaves /var/lib/luradb and the luradb user alone. Changes to the data format happen at the first start of the new binary.

An update restarts the service only if it is running

After unpacking, the package reloads systemd and runs try-restart on luradb.service: a running service restarts on the new binary, a stopped service stays stopped. The restart ends open connections, watch streams included; clients have to reconnect. The server shuts down gracefully on SIGTERM, and every confirmed write is in the write-ahead log, which the new process replays as far as it is not yet in the data files. A change you made to luradb.toml before the update takes effect with this restart.

Back up before an update that changes the format

A release may change what is on disk. Version 0.5.1 does:

• The write-ahead log path becomes a directory of 64 MiB segment files. A log file written by an earlier version at that path becomes such a directory on the first start.
• The engine files move into a shard_0/ directory beside the configured paths, see Multicore.
• Users, API key hashes and permissions move into a separate system store, at storage.system_dir.
• The write-ahead log header records the starting sequence number.

These changes happen automatically on the first start and are one-way. Once the new version has started on a data directory, an earlier version refuses to start on it, with an error that the write-ahead log is a directory, and changes no data. To go back, restore a backup taken before the update into the older version. Backup and restore describes how to take and restore one.

Read the changelog markers before you update

Every release in the changelog lists what changed, sorted into Added, Changed, Removed, Fixed and Security. Four markers tell you where to look first:

Marker	Example	What to check
API:	API: read-only log access — GET /store-api/logs … (0.3.0)	The REST API gained or changed an endpoint. Existing clients keep working unless the entry also says BREAKING.
**BREAKING** API:	GET /health reports per-shard status and answers 503 with status degraded when a shard does not respond. (0.5.1)	A client that calls the endpoint can see a different response.
**BREAKING**	Requires Linux kernel 6.1 or newer; the server refuses to start on older kernels. (0.5.1)	Something outside the REST API stops working until you act.
**BREAKING** Format:	the write-ahead log path is now a directory of segments; earlier versions cannot open a data directory written by this version. (0.5.1)	The data format changes; going back needs a backup.

Between two releases that are far apart, read every release in between.

The shard count stays as the data was written

The number of data shards belongs to the data directory. With multicore.shards at 0, its default, the server keeps the count the directory was written with, also after an update and on a host with more or fewer cores. If this host would pick a different count, the start log warns and prints the command that changes it:

WARN luradb::server::layout: Data shards: 1, as the data directory was written; this host would use 2. Writes stay on 1 core(s) until you stop the server and run: luradb --migrate-shards 2

When the count is the one stored, the log says Data shards: 2, as the data directory was written. A count that you set to another number than the stored one refuses the start:

Error: shard count changed (stored 2, configured 3) — run `luradb --migrate-shards 3`

Change the shard count

--migrate-shards rewrites the data directory for another number of data shards, more or fewer, down to 1. It works offline, moves key-value, JSON and relational data alike, and prints the result. With the packaged service:

sudo systemctl stop luradb
sudo -u luradb sh -c 'cd /var/lib/luradb && exec /usr/bin/luradb --config /etc/luradb/luradb.toml --migrate-shards 4'
sudo systemctl start luradb

INFO luradb::server::migrate: Changing the data shards from 1 to 2.
INFO luradb::server::migrate: Data shards: 2.
The data directory has 2 data shards.

• Run it from the directory the service runs in. Relative paths in the configuration count from the current directory, and the packaged service runs in /var/lib/luradb. From another directory the tool does not find the JSON and relational data and stops without changing anything.
• Stop the server first. The server holds a lock on <system_dir>/lock for as long as it runs. Started against a running server, the tool stops with stop the server before changing the shard count.
• Shut the server down cleanly. The tool refuses to run when a write-ahead log still holds writes that are not in the data files: start the server once, stop it again and rerun the tool.
• Leave room for a second copy of the data. The new layout is built in a migrate_<timestamp>/ directory inside each data directory and only then moved into place. The old layout is removed once the move has finished.
• Set multicore.shards to 0 or to the new count in luradb.toml; any other explicit value refuses the start.
• An interrupted run can be repeated. If the tool stops while it moves the new layout into place, the server refuses to start with shard migration incomplete — rerun the migration tool, and the same command finishes the change. A run stopped earlier leaves the old layout untouched.
• Backups are not affected. An archive restores into any shard count.

A removed configuration key is warned about and ignored

A release can drop configuration keys. Version 0.5.1 removed many tuning keys. A luradb.toml that still sets such a key starts normally and the value has no effect; the server logs one warning per key:

WARN luradb: unknown config key 'io_engine.ring_depth' is ignored
WARN luradb: unknown config key 'io_engine.sqpoll_enabled' is ignored
WARN luradb: unknown config key 'lsm.use_mmap' is ignored

The server makes no difference between a removed key and one that never existed, so the same warning also catches a typo. Look the key up in the removed keys of the configuration reference: each entry says in which release the key was removed and what replaced it or why it went, for example io_engine.sqpoll_enabledremoved or lsm.use_mmapremoved. After the update, read the start log once with journalctl -u luradb -b and remove or replace every key it warns about.

After the update

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

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

server_version is the release; api_version is the version of the REST contract, which changes independently of it. GET /health should answer "status": "ok"; see Resource guard for what degraded means.

Related settings multicore.shards · storage.wal_path · storage.system_dir · backup.enabled ·

backup.dir