Updating

Pulling a new image without losing history, and what happens to the schema.

operatorAssumes a terminal, Docker, and editing a config file.page 8 of 24

Pull, recreate, done. Migrations run in-process at startup, so there is no separate step and no window where the app is running against a schema it does not understand.

The update#

cd /opt/elele-dns
sudo docker compose pull
sudo docker compose up -d

The container stops, a new one starts on the same bind-mounted data directory, and any pending schema migrations are applied before the worker starts. Downtime is a few seconds and nothing is lost: ingest resumes from the it stored.

Before a major version#

Take a backup. It is one file and it takes a second.
Read the release notes for schema changes. Migrations are one-way; there is no down.
Pin the image if you want to control when this happens: image: hunterelele/elele-dns:1.4.2 rather than :latest.

pull

network-bound

stop

seconds

migrate

an index build on 3M rows

serve

answering again

Ingest resumes from its stored watermark afterwards, so nothing is lost to the gap — the queries that arrived during it are still in the resolver's log and get picked up on the next pass. The migrate segment is the only one that grows with your history.

What a migration does to a big store#

Most are instant. The ones that add an index to queries are not: on a three million row table an index build takes tens of seconds and the app will not answer until it finishes. That is a deliberate trade, since serving pages against a half-indexed table would mean minutes of full scans instead.

Rolling back#

Change the tag back and recreate. This works as long as the newer version did not migrate the schema; if it did, restore the backup you took, because an older binary against a newer schema is not a supported combination and will fail in ways that are not obvious.

Updating the resolver itself#

Independent of this, and safe to do whenever. Ingest will report lag while it restarts and catch up on its own afterwards. The only version-sensitive part is the query log API, which has been stable since 0.107.The version-sensitive part is the whole API: v6 replaced v5’s endpoints outright, so the one upgrade that matters is the one you have already done. Point upgrades within v6 have been safe, and a Pi-hole restart drops the dashboard’s session, which it re-establishes on the next poll rather than reporting as an error.