The week we added Compose to a Skylane project, a developer ran docker compose down -v to “clean up” before a demo. It cleaned up three days of carefully entered test data. Containers are disposable by design, so anything you want to keep must live outside them, and you need to know exactly which command throws it away.
Add a volume to the db service and declare it at the top level:
services:\n # api: …as before\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes\n volumes:\n - pgdata:/var/lib/postgresql/data\n\nvolumes:\n pgdata:A named volume is storage that Docker creates and manages. Compose prefixes it with the project name, so this one is notes_pgdata. It isn’t part of any container, so removing and recreating db leaves the data in place:
docker compose down # containers and network removed, pgdata kept\ndocker compose up -d # notes are still there\ndocker volume ls # notes_pgdata\ndocker volume inspect notes_pgdataNamed volumes are the right default for database files. Docker sets ownership correctly for the container, you don’t get host filesystem quirks, and on Docker Desktop they’re much faster than bind mounts because they live inside the Linux VM.
\n\nRestoring is the same pipe in the other direction: docker compose exec -T db psql -U notes notes < backup.sql. The -T flag turns off the pseudo-terminal so the file can be streamed in. It’s worth trying once on a quiet afternoon, so the first time you restore isn’t the day you need to.
A bind mount maps a path on your machine into the container. Edits on either side show up on the other immediately. That’s what you want for files that live in your repository, like a schema script:
\n db:\n image: postgres:17\n volumes:\n - pgdata:/var/lib/postgresql/data\n - ./db/init:/docker-entrypoint-initdb.d:roThe Postgres image runs every .sql and .sh file in /docker-entrypoint-initdb.d, in name order, only when the data directory is empty. On the very first up, db/init/001-schema.sql creates the notes table. On every later start, the folder is ignored, because the volume already holds an initialised database. When you change the schema after that, write a migration that the app runs, or deliberately wipe the dev volume.
The :ro suffix makes the mount read-only inside the container. Give containers the least access that works.
Bind mounts have two rough edges. On Linux, files are owned by the host user’s UID, which may not match the user inside the container, so writes fail with EACCES. On macOS and Windows, file access crosses the VM boundary and is slower, which is why heavy folders like node_modules should never be bind-mounted from the host. You’ll use a better tool for live code editing, Compose watch, in lesson 3.4.
A tmpfs mount lives in memory and disappears when the container stops. It’s useful for scratch files you never want on disk, or for a throwaway test database where speed matters more than survival:
db-test:\n image: postgres:17\n tmpfs:\n - /var/lib/postgresql/dataA volume stores the database’s on-disk format, which belongs to one major version. If you bump postgres:17 to postgres:18 and keep the same volume, the new server refuses to start on the old files. Postgres 18’s image also moved its default data location: it expects a single mount at /var/lib/postgresql (and keeps data in a version-named folder below it) rather than at .../data. Its entrypoint exits with an error explaining this if it finds data, or a mount, at the old path. Read the image’s release notes before bumping a major version.
| Need | \nUse | \n
|---|---|
| Database files that survive restarts | \nNamed volume | \n
| Seed scripts or config from the repo | \nBind mount, :ro | \n
| Fast, disposable scratch space | \ntmpfs | \n
| Your source code during development | \nCompose watch (lesson 3.4) | \n
Your data now outlives your containers. But start the stack from cold and you may see the API fail its first few requests: it starts before Postgres is ready to accept connections. Startup order is next.
\n","toc":[{"id":"sec-1","text":"Named volumes for database files","level":2},{"id":"sec-2","text":"Bind mounts for files you edit","level":2},{"id":"sec-3","text":"tmpfs for scratch data","level":2},{"id":"sec-4","text":"Volumes and database versions","level":2},{"id":"sec-5","text":"Which mount for which job","level":2}],"takeaways":["Named volumes are managed by Docker and outlive containers; use them for database files.","Bind mounts map a host path into a container; use them for files you edit on the host, such as seed scripts, and mount them read-only when you can.","docker compose down keeps named volumes; docker compose down -v deletes them along with all their data.","Scripts in /docker-entrypoint-initdb.d run only when the Postgres data directory is empty, which means on the very first start.","A database’s on-disk format is tied to its major version; upgrading Postgres across majors needs a dump and restore or pg_upgrade, not a new tag."],"further":[{"title":"Volumes","url":"https://docs.docker.com/engine/storage/volumes/"},{"title":"Bind mounts","url":"https://docs.docker.com/engine/storage/bind-mounts/"},{"title":"Compose volumes reference","url":"https://docs.docker.com/reference/compose-file/volumes/"}],"quiz":[{"q":"You run docker compose down and then docker compose up -d. The db service mounts the named volume pgdata. What happens to your notes?
down removes containers.","why":"The containers are removed, but the named volume is not. Postgres finds its data again on the next start."},{"text":"They’re gone unless you ran docker compose stop first.","why":"stop versus down affects containers, not named volumes. Both leave pgdata alone."},{"text":"They’re restored from the image’s initial snapshot.","why":"Images don’t snapshot data. The volume is what holds it."},{"text":"They’re still there; down doesn’t delete named volumes unless you add -v.","why":"Correct. Only docker compose down -v (or docker volume rm) deletes the volume."}],"answer":3},{"q":"You edit db/init/001-schema.sql to add a column, run docker compose up -d, and the column doesn’t appear. Why?
/docker-entrypoint-initdb.d on an initialised database. Use a migration, or wipe the dev volume on purpose."},{"text":"The file must be named init.sql exactly.","why":"Any .sql, .sql.gz or .sh file in that folder runs, in name order."},{"text":"The :ro flag stops Postgres from reading the file.","why":":ro stops the container from writing. Reading is fine."}],"answer":1},{"q":"Which mount should hold Postgres’s data in a development stack you want to survive restarts?
","options":[{"text":"A named volume such aspgdata:/var/lib/postgresql/data.","why":"Correct. Docker manages it, it outlives containers, and it avoids host file-permission and performance surprises."},{"text":"A tmpfs mount at /var/lib/postgresql/data.","why":"tmpfs lives in memory and vanishes when the container stops. Fine for throwaway tests, wrong here."},{"text":"The container’s writable layer, which is the default.","why":"That layer is deleted with the container, so docker compose down loses everything."},{"text":"A bind mount to your src/ folder.","why":"Mixing database files into your source tree invites accidental commits and permission errors."}],"answer":0},{"q":"You change the db image from postgres:17 to postgres:18 and keep the same pgdata volume. What should you expect?
pg_upgrade.","why":"Correct. Major upgrades are a migration. In development, dump, wipe the volume, restore; in production, plan it."},{"text":"The volume is automatically renamed to pgdata-18.","why":"Compose never renames volumes. It mounts exactly what the file names."}],"answer":2}],"exercise":{"kind":"choice","multiple":true,"options":["pg-named","init-bind","src-volume","pg-tmpfs","tmpfs-scratch"],"correct":["pg-named","init-bind","tmpfs-scratch"],"title":"Pick the right mount","prompt":"You’re reviewing storage choices in the notes-api Compose stack. Select every pairing of need and mount type that is correct.
\n","hints":["Ask two questions of each: should the data survive the container, and does it come from your repository?","A named volume never reflects edits you make in your editor; a tmpfs never survives a stop.","Three pairings are correct."],"explanation":"Postgres data belongs in a named volume: it survives down and avoids host permission and performance issues. Seed scripts live in the repo, so a read-only bind mount into /docker-entrypoint-initdb.d is right. Disposable scratch space is what tmpfs is for. A named volume for src/ would freeze a copy of your code that never sees your edits, and tmpfs for data you want to keep loses it on every stop.
pgdata:/var/lib/postgresql/data","why":"Correct. Named volumes outlive containers and are Docker-managed."},"init-bind":{"text":"SQL schema scripts from the repository → bind mount ./db/init:/docker-entrypoint-initdb.d:ro","why":"Correct. The files live in your repo and the container only needs to read them."},"src-volume":{"text":"Live-editing src/ during development → named volume src:/app/src","why":"A named volume is filled once and then independent of your host folder, so edits never reach the container. Use Compose watch or a bind mount."},"pg-tmpfs":{"text":"Postgres data you want to keep between workdays → tmpfs: /var/lib/postgresql/data","why":"tmpfs lives in memory; stopping the container erases it."},"tmpfs-scratch":{"text":"Temporary files for a test run that should vanish afterwards → tmpfs: /tmp/scratch","why":"Correct. Fast, never written to disk, gone when the container stops."}}},"words":732,"readMinutes":3}