Skip to main content

Upgrading LynxDB

LynxDB includes a built-in self-update mechanism. The binary can upgrade itself in place, or you can update through your package manager or container registry.

Check for Updates​

lynxdb upgrade --check
Update available: v0.4.0 -> v0.5.0
Changelog: https://github.com/OrlovEvgeny/Lynxdb/releases/tag/v0.5.0

If you are already on the latest version:

LynxDB v0.5.0 is up to date.

Self-Update (Single Binary)​

The simplest way to upgrade. The binary downloads the new version, verifies the checksum, and performs an atomic swap:

lynxdb upgrade
Checking for updates...
Downloading lynxdb v0.5.0 for linux/amd64...
100%  15.0MB
Checksum verified
Upgraded: v0.4.0 -> v0.5.0

Upgrade to a Specific Version​

lynxdb upgrade --version v0.5.0-rc.1

How Self-Update Works​

  1. Fetches manifest.json from dl.lynxdb.org (fallback: GitHub Releases)
  2. Compares the installed version with the latest version
  3. Downloads the new binary to a temporary file while computing SHA256
  4. Verifies the checksum matches the manifest
  5. Performs an atomic rename: .new -> current binary, old binary -> .old
  6. Cleans up .old file

The update is atomic -- if anything fails, the old binary remains in place.

Install Script​

Re-run the install script to upgrade:

curl -fsSL https://lynxdb.org/install.sh | sh

The script detects the existing installation and shows the version change:

LynxDB v0.4.0 is installed. Upgrading to v0.5.0...

Install a Specific Version​

LYNXDB_VERSION=v0.5.0 curl -fsSL https://lynxdb.org/install.sh | sh

Homebrew​

brew update
brew upgrade lynxdb/tap/lynxdb

Docker​

# Pull the latest image
docker pull OrlovEvgeny/Lynxdb:latest

# Or a specific version
docker pull OrlovEvgeny/Lynxdb:0.5.0

Docker Compose​

docker compose pull
docker compose up -d

Kubernetes​

# Update the image tag in your manifest
kubectl -n lynxdb set image statefulset/lynxdb lynxdb=OrlovEvgeny/Lynxdb:0.5.0

# Watch the rollout
kubectl -n lynxdb rollout status statefulset/lynxdb

Single-Node Upgrade Procedure​

With systemd​

# 1. Check for updates
lynxdb upgrade --check

# 2. Stop the server
sudo systemctl stop lynxdb

# 3. Upgrade the binary
sudo lynxdb upgrade
# or: curl -fsSL https://lynxdb.org/install.sh | sudo sh
# or: sudo lynxdb install --yes   (re-running install upgrades the binary in place)

# 4. Verify the new version
lynxdb version

# 5. Start the server
sudo systemctl start lynxdb

# 6. Verify health
lynxdb health
lynxdb status

Downtime: A few seconds (stop -> upgrade -> start).

Zero-Downtime with Load Balancer​

If you have a load balancer in front of LynxDB:

# 1. Remove from load balancer
# (configure health check to fail, or manually remove)

# 2. Wait for in-flight requests to complete
sleep 10

# 3. Stop, upgrade, start
sudo systemctl stop lynxdb
sudo lynxdb upgrade
sudo systemctl start lynxdb

# 4. Verify health
lynxdb health

# 5. Re-add to load balancer

Cluster Rolling Upgrade​

For cluster deployments, upgrade one node at a time to maintain availability:

Small Cluster (All Roles)​

# Upgrade nodes one at a time
for node in node-1 node-2 node-3; do
  echo "Upgrading $node..."

  # Stop the node
  ssh $node "sudo systemctl stop lynxdb"

  # Upgrade
  ssh $node "sudo lynxdb upgrade"

  # Start
  ssh $node "sudo systemctl start lynxdb"

  # Wait for the node to rejoin the cluster
  sleep 30

  # Verify health
  ssh $node "lynxdb health"

  echo "$node upgraded successfully."
done

Large Cluster (Role-Separated)​

Upgrade in this order to minimize disruption:

  1. Query nodes first (stateless, easiest to replace)
  2. Ingest nodes second (stateless after flush)
  3. Meta nodes last (maintain Raft quorum)
# 1. Query nodes (can upgrade in parallel, but rolling is safer)
for node in query-1 query-2 query-3; do
  ssh $node "sudo systemctl stop lynxdb && sudo lynxdb upgrade && sudo systemctl start lynxdb"
  sleep 15
  ssh $node "lynxdb health"
done

# 2. Ingest nodes (one at a time, wait for shard reassignment)
for node in ingest-1 ingest-2 ingest-3; do
  ssh $node "sudo systemctl stop lynxdb && sudo lynxdb upgrade && sudo systemctl start lynxdb"
  sleep 30  # Wait for shard reassignment + rejoin
  ssh $node "lynxdb health"
done

# 3. Meta nodes (one at a time, maintain quorum)
for node in meta-1 meta-2 meta-3; do
  ssh $node "sudo systemctl stop lynxdb && sudo lynxdb upgrade && sudo systemctl start lynxdb"
  sleep 30  # Wait for Raft leader election
  ssh $node "lynxdb health"
done

Kubernetes Rolling Update​

# Update the image in the StatefulSet
spec:
  template:
    spec:
      containers:
        - name: lynxdb
          image: OrlovEvgeny/Lynxdb:0.5.0  # New version
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0  # Update all pods
kubectl -n lynxdb rollout status statefulset/lynxdb

Version Compatibility​

Data Format Compatibility​

LynxDB maintains backward compatibility for the .lsg segment format. Newer versions can read segments written by older versions. In rare cases, a major version upgrade may require a one-time migration:

# If needed (check release notes), run the migration
lynxdb migrate

Config Compatibility​

New config keys are added with sensible defaults. Existing config files continue to work without changes. Unknown keys produce a warning during lynxdb config validate.

Rollback​

If an upgrade causes issues:

Single Node​

# The old binary is saved as lynxdb.old after self-update
sudo systemctl stop lynxdb
sudo mv /usr/local/bin/lynxdb.old /usr/local/bin/lynxdb
sudo systemctl start lynxdb

Install a Specific Older Version​

LYNXDB_VERSION=v0.4.0 curl -fsSL https://lynxdb.org/install.sh | sh

Docker​

docker pull OrlovEvgeny/Lynxdb:0.4.0
docker compose up -d

Release Channels​

ChannelURLDescription
Stabledl.lynxdb.org/manifest.jsonProduction-ready releases
Pre-releaselynxdb upgrade --version v0.5.0-rc.1Release candidates for testing

Checking Version​

lynxdb version

# Output:
# LynxDB v0.5.0 (abc1234) built 2026-03-01T10:00:00Z
# Go: go1.25.4 linux/amd64

Next Steps​