# Upgrading

> Upgrade HotKV On-Premise packages and containers, roll an upgrade through replicas and clusters, and what happens to your data files and license.

URL: https://docs.hotkv.com/operate/upgrading/


HotKV Cloud instances are upgraded for you. This page is for HotKV
On-Premise: upgrading a single server, rolling an upgrade through
replicas and clusters, and what carries over.

## Before you upgrade

1. Read the [changelog](https://docs.hotkv.com/changelog/index.md) for the new release.
2. Take a fresh snapshot and copy it somewhere safe:

   ```bash
   hotkv-cli -a "$PASSWORD" BGSAVE
   hotkv-cli -a "$PASSWORD" LASTSAVE     # changes once the save is done
   sudo cp /var/lib/hotkv/dump.hkv /backup/dump.hkv.$(date +%Y%m%d)
   ```

3. Copy your configuration (`/etc/hotkv/`), your ACL file if you use one,
   and your license file.
4. With encryption at rest, make sure you have the key file: a snapshot
   cannot be read without it.

## Upgrade a single server

Your account team sends you a private download link for each release.
Download the newer package from it, then install it over the old one:

```bash
# Debian / Ubuntu
sudo apt install ./hotkv-enterprise_*.deb
sudo systemctl start hotkv

# RHEL / Rocky / Fedora
sudo dnf install ./hotkv-enterprise-*.rpm
```

- **Debian and Ubuntu:** the package stops the service during the upgrade
  and does not start it again; start it yourself.
- **RHEL family:** the package restarts the service if it was running.

Stopping saves a snapshot first when save points are configured (and with
the AOF on every write is already in it), and the new version loads the
data at startup. The server is unavailable from the stop until the data is
loaded, so plan a short window or use replicas (below).

What the package keeps:

- `/etc/hotkv/hotkv.conf` is a configuration file: your edits are kept.
- Files the package does not own are not touched: your data in
  `/var/lib/hotkv`, your license file, your ACL file, certificates and
  keys.

Then check the new version is running:

```bash
hotkv-cli INFO server | grep hotkv_version
hotkv-cli LICENSE.INFO
```

For containers, recreate the container from the new image with the same
`/data` volume and settings; see
[Docker and Kubernetes](https://docs.hotkv.com/operate/docker-and-kubernetes/index.md#upgrade-a-container).

## Data files

Keep the snapshot (`dump.hkv`) you took before the upgrade. Rolling back
to the previous release needs it, because the previous release may not read
data written by the new one.

Encrypted snapshots carry over as long as the same key is configured.

## Your license

Your license file stays in place and the new version reads it from the same
`license-path`. If you move to new hardware, ask your account team for an
updated license before you move. See
[Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md#3-get-your-hardware-id).

## Rolling upgrades with replicas

With replicas, upgrade one node at a time so the data stays served:

1. Upgrade each replica in turn. After each one, wait until it has caught
   up with its primary (`master_link_status:up` in `INFO replication` on the
   replica, and equal offsets) before the next.
2. Promote an upgraded replica: `REPLICAOF NO ONE` (or `REPLICATION.FAILOVER`)
   on it, then point clients and the other replicas at it.
3. Upgrade the old primary and bring it back as a replica of the new one
   (`replicaof host port` in its configuration, or `REPLICAOF host port`).

## Rolling upgrades in a cluster

In cluster mode, failover moves the primary role for you. [Upgrading a
cluster](https://docs.hotkv.com/clustering/upgrades/index.md) walks through it on a running cluster with a client writing, step by
step:

1. Upgrade the replicas of every shard, one node at a time, waiting for
   `CLUSTER INFO` to report `cluster_state:ok` and the replica to be in
   sync before the next.
2. On an upgraded replica of each shard, run `CLUSTER FAILOVER`. It takes
   over as primary, and the old primary becomes its replica.
3. Upgrade the former primaries, now replicas, one at a time.

A rolling upgrade runs two versions side by side for a while. Keep that
time short and finish the upgrade on every node before you use new
settings.

> **Tip**
> Keep the snapshot from before the upgrade until the new version has run
> for a while. It is the simplest way back.

## Next steps

- [Install](https://docs.hotkv.com/get-started/install/index.md): packages, files and ports.
- [Upgrading a cluster](https://docs.hotkv.com/clustering/upgrades/index.md): the rolling procedure.
- [Clustering](https://docs.hotkv.com/clustering/index.md): failover and the cluster bus.
- [Persistence](https://docs.hotkv.com/persistence/index.md): snapshots and the AOF.