Docker Compose for PostgreSQL generator

The PostgreSQL data directory inside the container is at /var/lib/postgresql/data. Without a volume mount, this directory lives in the container's writable layer and is destroyed when the container is removed (docker compose down without -v, or docker rm). To persist data, mount a named volume: volumes: [pgdata:/var/lib/postgresql/data] and declare it in the top-level volumes: section. Named volumes survive container removal — only docker compose down -v or docker volume rm explicitly deletes them. A common mistake is mounting a bind-mount directory (like ./data:/var/lib/postgresql/data) on macOS or Windows, which works but is significantly slower than named volumes due to the filesystem translation layer in Docker Desktop. For development on macOS, named volumes give substantially better I/O performance because they are stored in the Linux VM rather than translated through VirtioFS or gRPC-FUSE. For CI, consider tmpfs mounts (tmpfs: [/var/lib/postgresql/data]) to avoid disk I/O entirely and speed up test runs — but understand the data is gone when the container stops. Note that docker compose down without -v preserves volumes, while docker compose down -v deletes them permanently.

The official postgres image runs files in /docker-entrypoint-initdb.d/ only once — on the very first startup when the data directory (/var/lib/postgresql/data) is empty. It processes .sql, .sql.gz, and .sh files in filename-sorted order (locale-dependent, so prefix with numbers like 01-schema.sql, 02-seed.sql). The most common reason scripts do not run is that the data directory already contains data from a previous run, so the entrypoint skips initialization entirely. To re-run init scripts, you must remove the volume: docker compose down -v && docker compose up. Other causes: the mount path is wrong (e.g., mounting a single file instead of a directory, or a typo in the path), the .sql file has a syntax error that causes the entrypoint to abort, or the script has incorrect file permissions (.sh files need to be executable). Check docker compose logs postgres for error messages during initialization. For scripts that should run on every startup (not just the first), use the command override or a custom entrypoint wrapper instead.

There are two reliable approaches. The first and most common is to mount the file as a read-only bind mount to a custom path and tell PostgreSQL to use it via the command override: volumes: [./postgresql.conf:/etc/postgresql/postgresql.conf:ro] with command: postgres -c config_file=/etc/postgresql/postgresql.conf. The :ro flag prevents accidental writes. The second approach is to use command to pass individual settings directly: command: postgres -c shared_buffers=256MB -c work_mem=16MB -c max_connections=100. This is simpler for a few settings but becomes unwieldy for many. A critical mistake is mounting the file directly to /var/lib/postgresql/data/postgresql.conf — this fails because the data directory is initialized by the entrypoint, and the mount conflicts with the initialization process. Similarly, do not mount a directory to a file path or vice versa; Docker will create a directory if the source does not exist, and PostgreSQL will fail to read a directory as a configuration file. For pg_hba.conf, mount it to a custom path and reference it via command: postgres -c hba_file=/etc/postgresql/pg_hba.conf.

No. The top-level version key (e.g., version: "3.8") is obsolete and ignored by modern Docker Compose (v2.x CLI, which replaced the older v1 Python-based docker-compose). The Compose Specification — the current standard — does not use a version key. Including it triggers a deprecation warning in recent Docker Compose versions and has no effect on behavior. The historical v2/v3 versioning caused significant confusion because version: "3" actually removed features from v2 (like mem_limit and condition in depends_on) in favor of Docker Swarm's deploy.resources syntax. The modern Compose Specification merges the best of both: deploy.resources.limits works for both local and Swarm deployments, depends_on supports condition: service_healthy, and features like profiles, extends, variable interpolation, and YAML anchors are all available without worrying about version compatibility. Simply start your file with services: as the top-level key. If you are following an older tutorial that includes version: "3.x", remove that line and everything else should work as-is with current Docker Compose. The Compose CLI v2 (invoked as docker compose with a space, not the hyphenated docker-compose) is the actively maintained version and ships with Docker Desktop by default.