Docker Compose: update while preserving application data

Identify what must survive

A Compose file describes services; it is not a backup of their data. Identify named volumes, bind mounts, databases and configuration files. Data stored only in a container’s writable layer may disappear when that container is replaced. Record the image tag or digest and the database schema version.

Prepare configuration

This fragment demonstrates a persistent volume for PostgreSQL 17. Match the version to the existing cluster: changing PostgreSQL’s major version is a migration, not a routine tag update. The variable must be available to Compose’s process environment.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Do not use a tutorial’s sample password as a production secret, and do not publish the file containing real values. docker compose config can print expanded environment values, so its output also needs careful handling.

Apply a controlled update

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80

Make a backup using a method supported by the database before this step. Archiving files from an active database is not automatically consistent. After starting the services, check logs, health checks and a real application operation, such as reading a previously saved record.

Verify recovery

Restoring an old image does not reverse database migrations. Test recovery in a separate project with a separate volume. Changing the Compose project name can select another similarly named volume, so compare resource identifiers as well. Do not use down -v or volume pruning as routine update steps.

Continue reading