Upgrading LynxDB
LynxDB is a single binary. Upgrading means replacing that binary with a newer release and restarting the server. On startup the server opens every index directory under data_dir from its manifest and continues from the state the stopped process left. There is no separate migration step.
Back up the data directory before upgrading a production server (see Backup and Restore).
Getting a Release
Install Script
Re-run the install script. It reads the stable manifest at https://dl.lynxdb.org/manifest.json, downloads the release for your platform, verifies its checksum, and replaces the installed binary:
curl -fsSL https://lynxdb.org/install.sh | sh
Install a specific version:
curl -fsSL https://lynxdb.org/install.sh | sh -s -- --version v0.5.0
# or
LYNXDB_VERSION=v0.5.0 curl -fsSL https://lynxdb.org/install.sh | sh
Install into a custom directory with --dir /opt/lynxdb/bin or LYNXDB_INSTALL_DIR.
Homebrew
brew update
brew upgrade lynxbase/tap/lynxdb
Docker
# Latest stable release
docker pull ghcr.io/lynxbase/lynxdb:latest
# A specific version
docker pull ghcr.io/lynxbase/lynxdb:0.5.0
With Docker Compose, update the image tag and recreate the container:
docker compose pull
docker compose up -d
GitHub Releases
Every release publishes archives and checksums on the GitHub releases page.
Nightly Builds
Nightly builds are prereleases built from main for testing. They may contain regressions and are not meant for production. Their versions look like v0.2.6-nightly.20261116.g403d8ad.
# Install script
curl -fsSL https://lynxdb.org/install.sh | sh -s -- --channel nightly --allow-prerelease
# Homebrew (a separate formula that installs the same lynxdb binary name)
brew install lynxbase/tap/lynxdb-nightly
brew upgrade lynxbase/tap/lynxdb-nightly
# Docker
docker pull ghcr.io/lynxbase/lynxdb:nightly
The install script reads the nightly manifest (https://dl.lynxdb.org/nightly/manifest.json) only when both --channel nightly and --allow-prerelease are given. To return to stable, re-run the install script without those flags, or brew uninstall lynxdb-nightly && brew install lynxbase/tap/lynxdb.
Single-Node Upgrade
With systemd
# 1. Stop the server
sudo systemctl stop lynxdb
# 2. Replace the binary
curl -fsSL https://lynxdb.org/install.sh | sudo sh
# 3. Check the version
lynxdb version --short
# 4. Start the server
sudo systemctl start lynxdb
# 5. Check health
lynxdb health
lynxdb status
Stopping the server writes the events it holds in memory and closes every index. Downtime is the time between stop and start.
Behind a Load Balancer
- Remove the node from the load balancer, or let its health check fail.
- Wait for in-flight requests to finish.
- Stop the server, replace the binary, start the server.
- Check
lynxdb health. - Add the node back.
Kubernetes
kubectl -n lynxdb set image statefulset/lynxdb lynxdb=ghcr.io/lynxbase/lynxdb:0.5.0
kubectl -n lynxdb rollout status statefulset/lynxdb
Several Servers
Servers that each own a data directory are upgraded independently, one at a time, with the single-node procedure above:
for host in lynxdb-1 lynxdb-2 lynxdb-3; do
ssh "$host" "sudo systemctl stop lynxdb"
ssh "$host" "curl -fsSL https://lynxdb.org/install.sh | sudo sh"
ssh "$host" "sudo systemctl start lynxdb"
ssh "$host" "lynxdb health"
done
A Kubernetes StatefulSet with updateStrategy: RollingUpdate replaces its pods one at a time after an image change:
kubectl -n lynxdb rollout status statefulset/lynxdb
Config Compatibility
A config key that the running release does not read is ignored, and the server prints a warning about it to stderr at startup. Check a config file against the installed release before the restart:
lynxdb config validate --config /etc/lynxdb/config.yaml
⚠ unknown config key "query.max_rows" in /etc/lynxdb/config.yaml
✔ Config file /etc/lynxdb/config.yaml is valid.
Rollback
To roll back, stop the server, install the older version, and start it again:
sudo systemctl stop lynxdb
curl -fsSL https://lynxdb.org/install.sh | sudo sh -s -- --version v0.4.0
sudo systemctl start lynxdb
With Docker, pin the older tag:
docker pull ghcr.io/lynxbase/lynxdb:0.4.0
docker compose up -d
A rollback works when the older release opens every index the newer one wrote. If the older server stops at startup with an error about an index, restore the backup taken before the upgrade.
Checking the Version
lynxdb version # version, commit, build date, Go runtime
lynxdb version --short # version string only
lynxdb version --json # structured output
Next Steps
- Backup and Restore -- back up before upgrading
- Monitoring -- check health after an upgrade
- Troubleshooting -- diagnose startup errors
- Configuration Overview -- configuration options