Docker, a pivotal tool in modern web development, offers an isolated and flexible environment for running various applications. Among these, PostgreSQL stands out as a popular choice for relational database management.
This guide aims to explain, step-by-step, how to install, run, and access PostgreSQL on Docker. It also covers some frequently asked questions about running PostgreSQL on Docker.
Installing & running Docker on macOS
When it comes to installing Docker on macOS, there are two options: Docker Desktop and Homebrew. Docker Desktop is the official Docker application for macOS, while Homebrew is a package manager that simplifies the installation process.
Docker App for Mac:
- Visit the Docker Documentation and download Docker for Mac.
- Open the installer and follow the on-screen instructions.
- Once installed, launch Docker from the Applications folder.
- Adjust preferences as needed to allocate resources like memory and CPU.
Homebrew Installation: Your can find the Homebrew formula for Docker here. Open Terminal and run
brew install --cask docker
To start Docker, run open /Applications/Docker.app
in Terminal. Docker will need some permissions to run, so follow the on-screen instructions to grant them.

Running PostgreSQL Using Docker
When it comes to running PostgreSQL within a Docker environment on macOS, you have two primary options:
-
Single Docker Command Method: This is a straightforward approach where you use a single command to start a PostgreSQL container. It's quick and easy, suitable for simple setups or individual developers. More details can be found on Docker's official PostgreSQL image page.
-
Docker Compose Method: This method involves using a
docker-compose.yml
file to define and run your PostgreSQL container. It's more scalable and maintainable, ideal for complex applications or team environments. Docker Compose documentation provides a comprehensive guide on this approach.
Both methods have their advantages, and the choice largely depends on your specific project needs and preferences, but for a local first setup I recommend the Single Docker Command Method.
Install PostgreSQL with a Single Docker Command Method
Open Terminal and enter:
docker run -d --name my_postgres -v my_dbdata:/var/lib/postgresql/data -p 54320:5432 -e POSTGRES_PASSWORD=my_password postgres:15-alpine
This command does the following:
-d
: Runs the container in detached mode.--name
: Assigns a name to your container.-v
: Creates a volume for data persistence.-p
: Maps a port from the container to your host machine.-e
: Sets environment variables, like the PostgreSQL password.
The PostgreSQL 15 image will be pulled and run in the container named 'my_postgres'.
Install PostgreSQL with Docker Compose file
Create a directory for your project and navigate into it.
Make a docker-compose.yml
file with:
version: "3"
services:
db:
image: "postgres:13"
container_name: "my_postgres"
environment:
POSTGRES_PASSWORD: "my_password"
ports:
- "54320:5432"
volumes:
- my_dbdata:/var/lib/postgresql/data
Run docker-compose up -d
to start PostgreSQL in a Docker container.
Your docker PostgreSQL container will be mounted. You can check it with docker ps
.
Accessing the PostgreSQL Docker Container
You know have docker running with PostgreSQL, but how do you access it?
First thing first, open the Docker App, and you'll see the container running. If for any reason it isn't running just click the start button.
To interract with the container you'll use the docker exec
command and then to access PostgreSQL you'll use the psql
command. Open a new Terminal window and run:
docker exec -it my_postgres psql -U postgres
If you need to troubleshoot something, you can access docker logs for that container using the docker logs
command:
docker logs -f my_postgres
You can access your PostgreSQL database right from your preferred DB client, like TablePlus I use as an example here: Use the port, db_name, user and password defined when you created the Docker Container.
FAQ
How to install different PostgreSQL versions
- Create distinct Docker volumes and containers for each PostgreSQL version.
- For instance, PostgreSQL 13 can be run on port
5013
and PostgreSQL 12 on5012
. - Use different container names like
postgres-13
andpostgres-12
for clarity.
How to connect to different PostgreSQL versions containers
- Have each Docker container running for each version on a specific port. You can use the
psql
command, or configure your app or client with port corresponding to the Postgres version you need to access to.
How to run PostgreSQL Docker Containers on Boot:
- Utilize Docker’s
--restart
flag to control container behavior on boot. - Options like
always
,unless-stopped
, andon-failure
offer flexibility in managing container lifecycles. - For instance,
docker run -d --restart unless-stopped postgres:13
ensures the container restarts automatically unless explicitly stopped.
How to run PostgreSQL Docker Containers in the Background:
- Use the
-d
flag to run containers in the background. - For instance,
docker run -d postgres:13
runs the container in the background.
How to stop PostgreSQL Docker Containers:
- Use the
docker stop
command to stop a container. - For instance,
docker stop my_postgres
stops the container namedmy_postgres
.