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.
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:
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.
When it comes to running PostgreSQL within a Docker environment on macOS, you have two primary options:
docker-compose.yml file to define and run your PostgreSQL container.
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.
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'.
Create a directory for your project and navigate into it.
docker-compose.yml file with:
docker-compose up -d to start PostgreSQL in a Docker container.
Your docker PostgreSQL container will be mounted. You can check it with
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.
How to install different PostgreSQL versions
5013 and PostgreSQL 12 on
postgres-12 for clarity.
How to connect to different PostgreSQL versions containers
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:
--restart flag to control container behavior on boot.
on-failure offer flexibility in managing container lifecycles.
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:
-d flag to run containers in the background.
docker run -d postgres:13 runs the container in the background.
How to stop PostgreSQL Docker Containers:
docker stop command to stop a container.
docker stop my_postgres stops the container named
Free 7-day trial. No credit card required.
Have a question? Need help getting started?
Get in touch via chat or at [email protected]