# Upgrade

Move a running nxdns to a newer release without losing its configuration or its history. The new binary upgrades the databases in place the first time it starts.

## 1. Read the release notes

Each release's notes are its section of the [changelog](../../CHANGELOG.md). nxdns is not at 0.1 yet, and a release can still change behaviour or settings on purpose; the notes say what changed and what to do about it.

## 2. Take a backup

In database mode, export the configuration first:

```sh
nxdns export --out /var/backups/nxdns-config.zon
```

The export is written at mode 0600 and carries the admin password's hash, so keep it as private as the database. In file mode your configuration file is already the backup. [Back up and restore](back-up-and-restore.md) has the details.

## 3. Replace nxdns

### systemd

Download and verify the new release as in [Install with systemd](install-with-systemd.md#1-download-and-verify), taking `aarch64` for a Raspberry Pi. Then, as root, from the unpacked directory:

```sh
install -m 0755 nxdns /usr/local/bin/nxdns
systemctl restart nxdns
journalctl -u nxdns -f
```

The tarball also carries `nxdns.service` and `nxdns.conf`. Reinstall them only when the release notes say they changed.

### Docker

The compose file names the release it belongs to, so fetch the new release's copy over yours, then pull and recreate the container:

```sh
cd ~/nxdns
curl -fLO https://git.mial.net/mokhtar/nxdns/raw/tag/v<version>/deploy/docker/compose.yaml
docker compose pull
docker compose up -d
```

If you edited your compose file, carry your edits over to the new one. To keep your file exactly as it is, skip the `curl` and set the release on both commands instead: `NXDNS_VERSION=<version> docker compose pull`, then `NXDNS_VERSION=<version> docker compose up -d`.

The container is recreated on the same `nxdns-data` volume, so the configuration and history stay.

### Nix

Change the tag in the flake input and switch; see [Install with Nix](install-with-nix.md#3-upgrade).

## 4. Confirm

```sh
nxdns version
dig @127.0.0.1 example.com A +short
```

`version` prints the release you installed. The start log names it too:

```
info(nxdns): nxdns <version> serving on udp [::]:53 tcp [::]:53 tcp 0.0.0.0:53; 1 upstream(s); blocklist generation 1
```

## What happens to the databases

A release that changes how data is stored upgrades `config.db` and `querylog.db` when it first starts, and logs it:

```
info(migrations): config.db migrated from schema version 0 to 1
```

Before it upgrades the query history, nxdns copies it to `querylog.db.pre-migrate-<unix-seconds>` beside the original and keeps that copy. An upgrade either completes or leaves the file as it was; if it fails, nxdns refuses to start and says so, and the history is untouched.

A release can also be unable to convert the old query history. Its release notes then say `resets your query history` and explain how to keep the old file. That release refuses to start until you move the old file aside, and its message says how; [Files and directories](../reference/files-and-directories.md#the-query-history-database) has the commands.

## Going back to an older release

Upgrades only go forward. An older nxdns refuses a database a newer one has already upgraded, and exits 2:

```
warning(migrations): config.db is at schema version 99; this nxdns binary supports 1
nxdns run failed: SchemaTooNew
```

To go back anyway, install the older `nxdns` and give it a fresh data directory with the configuration you exported in step 2. As root:

```sh
systemctl stop nxdns
mv /var/lib/nxdns /var/lib/nxdns.newer
nxdns import /var/backups/nxdns-config.zon
```

If the upgrade converted the query history, nxdns kept a copy of it from before; restore that copy to keep the history:

```sh
cp /var/lib/nxdns.newer/querylog.db.pre-migrate-* /var/lib/nxdns/querylog.db
```

Then hand the directory to the service and start it:

```sh
chown -R nxdns:nxdns /var/lib/nxdns
systemctl start nxdns
```

Blocklists download again on the first start. Anything recorded after the upgrade stays in `/var/lib/nxdns.newer`.