Backups, Migration, and Persistence Patterns

A named volume keeps data alive across container churn, but it does nothing to protect against a deleted volume, a corrupt database, or a dead host — that's what backups are for, and Docker has no built-in backup command. The standard pattern is a throwaway helper container that mounts the volume and tars its contents out to the host. The same trick moves a volume between hosts.

Underneath all of it sits the rule this chapter has been building toward: the image carries the application, the volume carries the data, and the two are versioned and protected by completely different mechanisms. Conflate them and you get bloated images that still don't protect the data. Keep them separate and each gets the treatment it actually needs.

There Is No docker volume backup

Docker will not snapshot a volume for you. There is no docker volume backup command, and looking for one is the first wrong turn. You back a volume up by mounting it into a short-lived container alongside a host directory and copying the data out yourself — which is why the helper-container pattern is the canonical answer rather than a single flag. It feels like a workaround the first time; it is simply how volume backup works.

The tar Backup Pattern, in Words

One disposable container produces one portable archive. It mounts the volume read-side at /data, mounts the current host directory at /backup, tars the contents of /data into a file on the host, and the --rm discards the helper the instant it exits. The image is busybox because it's tiny and ships tar — you need nothing heavier.

docker run --rm \
  -v driftwood-db-data:/data \
  -v $(pwd):/backup \
  busybox \
  tar czf /backup/driftwood-db.tar.gz -C /data .

Read it mount by mount: -v driftwood-db-data:/data attaches the volume you're backing up, -v $(pwd):/backup bind-mounts the current host directory so the archive lands on the host, and tar czf /backup/driftwood-db.tar.gz -C /data . changes into /data and tars its contents — the -C matters, because it stores relative paths that restore cleanly into any target volume. The --rm means no stopped helper container is left behind.

Restore and Migration

Restoring reverses the same shape: a helper container mounts the target volume and the archive, then untars into the volume. Migrating a volume to another host is just back up, copy the tarball across, restore on the far side — the volume becomes a portable artifact independent of any one machine.

docker volume create driftwood-db-data

docker run --rm \
  -v driftwood-db-data:/data \
  -v $(pwd):/backup \
  busybox \
  tar xzf /backup/driftwood-db.tar.gz -C /data

Create the target volume, mount it at /data and the directory holding the archive at /backup, and untar into /data. Because the archive stored relative paths, the contents land at the volume root regardless of which host or which volume name you're restoring into — which is exactly what makes the same two commands a migration tool, not just a backup tool.

Quiesce the Database First

taring a live Postgres data directory can capture a torn, mid-write state — pages half-flushed, the write-ahead log out of sync with the heap — and you only discover it's unrestorable when the restore won't start. For a database, take a logical dump with pg_dump, or stop or quiesce the container before archiving the volume, so the backup is consistent rather than merely present. A backup that restores into a broken database is not a backup; it's a false sense of security with a timestamp on it.

Data Belongs in a Volume, Not the Image

Never docker commit a container's data into an image, and never COPY a database into a Dockerfile. The image is the application artifact; the volume is the data, backed up out-of-band on its own schedule. Baking data into the image balloons it, ships the whole dataset on every push, and still leaves the data unprotected against the failures backups exist for. Keep the boundary clean — application in the image, data in the volume — and each is versioned and recovered the right way. That boundary is the through-line of this whole chapter, and it carries straight into the next one, where the Driftwood stack starts talking over a network.