Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 111 ยท Data and Volumes

Backup and Restore

Back up and restore Docker volumes with a helper container and tar, copy data between volumes and hosts, and use pg_dump for consistent database backups.

Docker volumes hold the data you cannot afford to lose: databases, uploads, configuration written by an application. Yet the Docker CLI has no docker volume backup command. A volume is just a folder managed by the daemon, and on Docker Desktop that folder lives inside a hidden virtual machine, so you cannot simply copy it with a file manager. The standard answer is a small, throwaway helper container that mounts the volume and a host folder together and runs tar between them.

This lesson shows that pattern step by step, then the cases it does not cover well: restoring on another machine, copying a volume to a new volume, and databases, where a file-level copy of a running server can be corrupt and a proper dump is the right tool.

The idea: a helper container that sees both sides

A container can mount several things at once. To back up a volume, start a short-lived Alpine container that mounts:

  1. the volume to back up (read-only, so the backup cannot change it),
  2. a folder on your host (a bind mount) where the archive will land.

Then run tar inside it.

TEXT
   Docker volume "app-data"                host folder ./backups
          โ”‚ (read-only)                          โ–ฒ
          โ–ผ                                      โ”‚
        /source โ”€โ”€โ”€โ”€ tar czf โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ /backup/data-backup.tar.gz
              โ””โ”€โ”€โ”€โ”€ helper container (alpine, --rm) โ”€โ”€โ”€โ”€โ”˜

Alpine is 8 MB and already contains tar and gzip, and --rm removes the helper as soon as it exits.

Backing up a volume

First create a volume with something in it. A throwaway container fills it with a folder, a file, and a file owned by user 1000 so that we can check that ownership survives:

CONSOLE
$ docker volume create app-data
app-data
$ docker run --rm -v app-data:/data alpine sh -c 'mkdir -p /data/notes; echo "buy milk" > /data/notes/todo.txt; echo "v1" > /data/version; chown 1000:1000 /data/version'

Now the backup:

CONSOLE
$ mkdir backups
$ docker run --rm \
    -v app-data:/source:ro \
    -v "$PWD/backups:/backup" \
    alpine tar czf /backup/data-backup.tar.gz -C /source .
$ ls -l backups
-rw-r--r-- 1 you you 205 Oct 23 18:34 data-backup.tar.gz

Reading the command piece by piece:

  • -v app-data:/source:ro mounts the volume by name, read-only.
  • -v "$PWD/backups:/backup" is a bind mount of the host folder. A host path is needed so the archive lands on your machine and not in the helper's disposable filesystem.
  • tar czf /backup/data-backup.tar.gz -C /source . creates (c) a gzip-compressed (z) file (f). -C /source . changes into the volume first, so the paths inside the archive start with ./ instead of containing a long absolute path. That keeps the archive restorable anywhere.

Always look inside the archive before you trust it. List it with tar t:

CONSOLE
$ docker run --rm -v "$PWD/backups:/backup:ro" alpine tar tzvf /backup/data-backup.tar.gz
drwxr-xr-x root/root         0 2026-10-23 14:34:56 ./
-rw-r--r-- 1000/1000         3 2026-10-23 14:34:56 ./version
drwxr-xr-x root/root         0 2026-10-23 14:34:56 ./notes/
-rw-r--r-- root/root         9 2026-10-23 14:34:56 ./notes/todo.txt

Owners and permissions are recorded (1000/1000 on version). That matters for the restore: tar run as root puts the owners back.

Name the archive with a date so that backups do not overwrite each other: -v "$PWD/backups:/backup" plus tar czf /backup/app-data-$(date +%F).tar.gz .... Run it from cron or a scheduler, then copy the folder off the machine. A backup on the same disk as the data protects against mistakes, not against disk failure.

Restoring into a new volume

A restore is the same pattern backwards: mount an empty volume read-write, mount the backups read-only, and extract.

CONSOLE
$ docker volume create app-data-restored
app-data-restored
$ docker run --rm \
    -v app-data-restored:/target \
    -v "$PWD/backups:/backup:ro" \
    alpine tar xzf /backup/data-backup.tar.gz -C /target
$ docker run --rm -v app-data-restored:/d:ro alpine sh -c 'ls -lA /d; cat /d/notes/todo.txt'
total 8
drwxr-xr-x    2 root     root          4096 Oct 23 14:35 notes
-rw-r--r--    1 1000     1000             3 Oct 23 14:34 version
buy milk

The folder, the file and the owner 1000 are all back. To bring a stopped application back to life, start it with -v app-data-restored:/data (or point your Compose file at the new volume).

Restore into an empty volume, and never into one that a running container is using. Extracting over live files mixes old and new data. If you must replace the contents of an existing volume, stop the containers that use it first, then clear the volume or create a fresh one.

Copying a volume to another volume

You do not need an archive to clone a volume, for example to test a risky upgrade on a copy. Mount both volumes and use cp -a, which preserves owners and permissions:

CONSOLE
$ docker volume create app-data-copy
app-data-copy
$ docker run --rm -v app-data:/from:ro -v app-data-copy:/to alpine cp -a /from/. /to/
$ docker run --rm -v app-data-copy:/d:ro alpine ls -lA /d
total 8
drwxr-xr-x    2 root     root          4096 Oct 23 14:34 notes
-rw-r--r--    1 1000     1000             3 Oct 23 14:34 version

Note the trailing /. in /from/.: it copies the contents of the folder, including hidden files. /from/* would skip names that start with a dot.

Migrating data to another machine

Combine the two recipes. On the old host, create the archive; copy the single file (with scp, rsync or a USB stick); on the new host, create a volume and extract:

Terminal
# old host
docker run --rm -v app-data:/source:ro -v "$PWD:/backup" alpine \
  tar czf /backup/app-data.tar.gz -C /source .

scp app-data.tar.gz newhost:/tmp/

# new host
docker volume create app-data
docker run --rm -v app-data:/target -v /tmp:/backup:ro alpine \
  tar xzf /backup/app-data.tar.gz -C /target

Because tar runs as root inside the helper on both ends, numeric owners come across unchanged. That only helps when the user IDs mean the same thing on both sides, which they do when the same image runs the application.

Backing up with --volumes-from

If a container is running and you do not remember its volume names, --volumes-from mounts every volume of that container into the helper at the same paths:

CONSOLE
$ docker run --rm --volumes-from db -v "$PWD/backups:/backup" alpine \
    sh -c 'tar czf /backup/pgdata.tgz /var/lib/postgresql/data 2>&1 | head -3; ls -l /backup/pgdata.tgz'
tar: removing leading '/' from member names
-rw-r--r--    1 root     root       7559540 Oct 23 14:36 /backup/pgdata.tgz

That produces a file, but whether it is a good backup depends on what the container is doing. Which brings us to databases.

Databases: dump, do not copy files

A database server keeps its files consistent through its own memory and logs. If you tar the data directory while the server is running, you may capture files from different moments in time. The archive can look fine and fail to start. There are two safe options:

  1. Stop the container, then copy the volume. This always works but means downtime.
  2. Ask the database for a logical dump, a text or binary file with the schema and rows, produced while the server keeps running. This is the normal approach.

Here is a PostgreSQL container with a small table:

CONSOLE
$ docker run -d --name db -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=shop \
    -v pgdata:/var/lib/postgresql/data postgres:17-alpine
$ docker exec db psql -U postgres -d shop -c "create table items(id serial primary key, name text); insert into items(name) values ('pen'),('book'),('lamp');"
CREATE TABLE
INSERT 0 3

pg_dump runs inside the container and writes to its standard output. The shell on your host redirects that output into a file:

CONSOLE
$ docker exec db pg_dump -U postgres -d shop > backups/shop.sql
$ grep -n -E "CREATE TABLE|COPY public" backups/shop.sql
30:CREATE TABLE public.items (
71:COPY public.items (id, name) FROM stdin;
$ docker exec db pg_dump -U postgres -Fc -d shop > backups/shop.dump
$ ls -l backups/shop.sql backups/shop.dump
-rw-r--r-- 1 you you 1974 Oct 23 18:35 backups/shop.sql
-rw-r--r-- 1 you you 2631 Oct 23 18:35 backups/shop.dump

The first file is plain SQL you can read; the second (-Fc) is PostgreSQL's compressed custom format, which allows restoring single tables. Do not use docker exec -t for a dump: -t allocates a terminal and adds carriage returns, corrupting the file.

To restore, delete the database and feed the file back in. For plain SQL, use psql and -i so that standard input stays open:

CONSOLE
$ docker exec db psql -U postgres -c "drop database shop;" -c "create database shop;"
DROP DATABASE
CREATE DATABASE
$ docker exec -i db psql -U postgres -d shop -q < backups/shop.sql
$ docker exec db psql -U postgres -d shop -c "select * from items order by id;"
 id | name 
----+------
  1 | pen
  2 | book
  3 | lamp
(3 rows)

For the custom format use pg_restore:

CONSOLE
$ docker exec db psql -U postgres -c "drop database shop;" -c "create database shop;"
DROP DATABASE
CREATE DATABASE
$ docker exec -i db pg_restore -U postgres -d shop < backups/shop.dump
$ docker exec db psql -U postgres -d shop -tc "select count(*) from items;"
     3

MySQL and MariaDB work the same way with mysqldump and mysql, and Redis writes its own snapshot with redis-cli --rdb or BGSAVE. The pattern is always: use the database's own tool, run it with docker exec, redirect to a host file. Passwords go in via environment variables or a .pgpass file, never on a command line that other users could see.

A restore test is the real backup

A backup you have never restored is a hope, not a backup. Schedule a periodic test that restores the latest archive into a fresh volume, starts a container on it and runs a query. It is also a good time to measure how long recovery takes.

Choosing a method

Situation Method
Files only (uploads, configuration, static data) Helper container with tar
Clone for testing cp -a between two volumes
Running database Logical dump (pg_dump, mysqldump)
Database with downtime allowed Stop container, then tar the volume
Move to another host Archive, copy, extract into a new volume
Bind-mounted folders Back up on the host with your normal tools

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does a volume backup use a helper container that mounts both the volume and a host folder?

    A volume is managed by the daemon, and on Docker Desktop it sits inside a VM. A short-lived container with a bind mount gets the data out in a portable way.
  2. 2. What does the -C /source . part of tar czf /backup/x.tar.gz -C /source . achieve?

    Relative paths make the archive restorable into any directory or volume, without a long absolute path baked in.
  3. 3. You want to restore a backup into a volume. What is the safest approach?

    Extracting over files that a running container uses mixes old and new data. An empty volume gives a clean result.
  4. 4. Which is the recommended way to back up a running PostgreSQL container?

    pg_dump produces a consistent snapshot while the server runs. Copying live data files can capture inconsistent state.
  5. 5. Why should you not add -t to docker exec when redirecting a dump into a file?

    A pseudo-terminal adds carriage returns and mixes stderr into the stream. Use docker exec without -t (and -i only when you pipe data in).

Summary

  • There is no built-in volume backup command; use a throwaway helper container that mounts the volume (read-only) and a host folder, and runs tar.
  • Use -C /source . for relative paths, and tar tzvf to inspect an archive.
  • Restore into a fresh, empty volume; cp -a clones one volume into another.
  • To migrate, create the archive, copy the file, and extract into a new volume on the target host.
  • For databases use the native dump tool (pg_dump, mysqldump) through docker exec, without -t.
  • Test restores regularly, and keep copies off the machine.

Next: Volume Drivers and Remote Storage