Skip to main content
0 reactions

How to Run PostgreSQL in Docker with Docker Compose

A Terminal window showing docker compose up -d creating the network, the volume and the container, then docker compose exec running psql, which answers with the server version 18.7.
PostgreSQL 18.7 running in Docker, checked with psql.

PostgreSQL is a free, powerful database, and Docker can run it without installing anything else on your computer. This guide runs PostgreSQL in Docker with Docker Compose: one short file, compose.yaml, and one command start it. Then you connect to it with psql and stop it again without losing your data.

At the end, you’ll have PostgreSQL 18 running in a Docker container on your computer, reachable at localhost:5432 from your computer only, with its data kept in a Docker volume.

Prerequisites

Every command here works the same in Terminal on macOS and Linux and in PowerShell on Windows.

Step 1: Create the compose.yaml File

Make a new folder named postgres-docker. In your code editor, create a file named compose.yaml in it:

YAML
services:
  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: local-only-password
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:
  • services lists the containers to run. There’s one, named db.
  • image: postgres:18 is the official PostgreSQL image at version 18, the newest release.
  • POSTGRES_PASSWORD sets the password of the default user, postgres. It’s the one setting the image requires. Choose your own; this one only protects a database on your own computer.
  • "127.0.0.1:5432:5432" makes PostgreSQL reachable on port 5432, PostgreSQL’s usual port, and only from your own computer. Without 127.0.0.1, Docker would accept connections from other computers on your network too.
  • pgdata:/var/lib/postgresql keeps the database files in a Docker volume named pgdata, so your data survives when the container is removed. From version 18, the image keeps its data in this folder.

Tip: If PostgreSQL is already installed on your computer, it’s probably using port 5432. Change the first number, for example to "127.0.0.1:5433:5432", and connect to port 5433.

Step 2: Start PostgreSQL

Open Terminal (PowerShell on Windows) in the postgres-docker folder, and run:

Bash
docker compose up -d

up starts everything in compose.yaml, and -d runs it in the background, so you get your Terminal back. Docker creates a network, the volume and the container:

Plain text
[+] up 3/3
 ✔ Network postgres-docker_default Created                                            0.0s
 ✔ Volume postgres-docker_pgdata   Created                                            0.0s
 ✔ Container postgres-docker-db-1  Started                                            0.2s

If the PostgreSQL image isn’t on your computer yet, Docker downloads it first and shows an extra Pulled line.

Step 3: Check That It’s Running

Bash
docker compose ps
Plain text
NAME                   IMAGE         COMMAND                  SERVICE   CREATED         STATUS        PORTS
postgres-docker-db-1   postgres:18   "docker-entrypoint.s…"   db        2 seconds ago   Up 1 second   127.0.0.1:5432->5432/tcp

STATUS says Up, and PORTS shows port 5432 on 127.0.0.1, your own computer.

Step 4: Connect with psql

psql is PostgreSQL’s command-line tool, and the image already includes it. This command runs it inside the container and asks PostgreSQL for its version:

Bash
docker compose exec db psql -U postgres -c 'SHOW server_version;'
  • docker compose exec db runs a command inside the running db container.
  • psql -U postgres connects as the default user, postgres.
  • -c '…' runs one SQL command and returns.
Plain text
        server_version
-------------------------------
 18.7 (Debian 18.7-1.pgdg13+2)
(1 row)
A Terminal window showing docker compose up -d creating the network, the volume and the container, then docker compose exec running psql, which answers with the server version 18.7.
PostgreSQL 18.7 running in Docker, checked with psql.

Your apps on this computer connect with this address: postgres://postgres:local-only-password@localhost:5432/postgres. More on running commands in a container: How to Run a Command Inside a Running Docker Compose Container (opens in a new tab).

Clean Up When You’re Done

To stop PostgreSQL and remove its container, run this in the postgres-docker folder:

Bash
docker compose down
Plain text
[+] down 2/2
 ✔ Container postgres-docker-db-1  Removed                                            0.2s
 ✔ Network postgres-docker_default Removed                                            0.1s

The volume stays, so docker compose up -d starts PostgreSQL again with all your data.

Warning: docker compose down -v also deletes the volume, and every database in it. Use it only when you no longer need the data.

Bash
docker compose down -v
Plain text
[+] down 1/1
 ✔ Volume postgres-docker_pgdata Removed                                              0.0s

More ways to stop and start without losing data: How to Stop, Start and Remove Docker Compose Containers Without Losing Data (opens in a new tab).

Common Mistakes

MistakeWhat happensDo this instead
Mounting the volume at /var/lib/postgresql/data with PostgreSQL 18The data isn’t stored where the image keeps it from version 18Mount it at /var/lib/postgresql
Leaving out POSTGRES_PASSWORDThe container stops with Error: Database is uninitialized and superuser password is not specified.Set your own password
Writing "5432:5432" without 127.0.0.1Other computers on your network can reach the databaseKeep 127.0.0.1: in front
Running docker compose down -v to stopThe volume and all your data are deletedUse docker compose down

Troubleshooting

ProblemCauseFix
psql shows a screen that ends with (END)The answer is wider than your Terminal, so psql opened its pagerPress q, or widen the window
Port 5432 is already in useAnother PostgreSQL runs on your computerChange the first port number (see the tip in Step 1)
Something else goes wrongThe container’s log says whySee How to See the Logs of a Docker Compose Service (opens in a new tab)

FAQ

Do I need to install PostgreSQL?

No. The image contains PostgreSQL and psql, so Docker Desktop is all you need.

Where is my data?

In the Docker volume, named postgres-docker_pgdata after the folder. It stays until you delete it with docker compose down -v.

Is PostgreSQL free?

Yes. PostgreSQL is open source and free to use. Docker Desktop is free for personal use, education and small businesses.

Conclusion

One compose.yaml file and docker compose up -d give you PostgreSQL 18 on your own computer, with its data in a volume that survives restarts. docker compose down stops it without losing anything.

Additional Resources

PostgreSQL, Docker and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by the PostgreSQL Global Development Group or Docker, Inc.

0 comments