How to run postgres in docker ?

Installing PostgreSQL directly on your local machine can be a hassle—lengthy steps, OS-specific quirks, and potential conflicts. Luckily, Docker makes the process super simple, fast, and portable. Let’s walk through how to run PostgreSQL in a Docker container. Why postgres in docker ? You don’t need to install PostgreSQL directly on your system. You can run multiple versions of PostgreSQL Docker isolates the database from your host OS—less risk of breaking other things. Install Docker Desktop First you need to download docker desktop and install it and sign up. If you have already done this, you can skip this process. Please make sure docker desktop is running the entire process. Running PostgreSQL Container Open the terminal and run the command docker run --name docker-postgres -e POSTGRES_PASSWORD=mypassword -p 5431:5432 -d postgres:16 Breakdown --name : name stands for name of the container. -e : e stands for environment variables. We are setting one environment POSTGRES_PASSWORD. POSTGRES_USER is assigned default to postgres. You can change it if you want using the same name env variable. -d : d stands for detached mode. postgres:16 : This is the image that will run. If postgres:16 image is already present , it will use that image. If not it will pull from the dockerhub. -p 5431:5432: Maps port 5432 on your host (localhost) to port 5432 in the container. If you have PostgreSQL already installed locally, change the host port (e.g., -p 5431:5432) to avoid conflicts. -e POSTGRES_DB=mydatabase : If this env is not added then default db with name postgres is created. If you want to name your database something else you can use this env. After running this command, verify the container is running in Docker Desktop UI: Check if docker container is running docker ps It should give you a list of all the container that are running right now. check for your container name. Connect to postgres Now in order to connect to postgreql running in docker container, run the command docker exec -it docker-postgres psql -U postgres Breakdown: docker-postgres: your container name psql: the command to run inside the container. psql comes with postgres image. -U postgres: tells psql which user to connect as -it : Runs the container in interactive mode and allocates a virtual terminal exec : Execute a command inside a running container How to create a new database. If no POSTGRES_DB env is given while creating the container, you will be assigned the default database named postgres. If you want a new database, run the command CREATE DATABASE outline_database; How to check all the database inside the container \l Press q to exit the psql shell pager. What's Next? Now that you have PostgreSQL running inside Docker, you can: Connect using a GUI like pgAdmin, TablePlus, or DBeaver. Use it in your local dev projects. Persist data using Docker volumes (explored in future posts

Apr 6, 2025 - 10:51

Installing PostgreSQL directly on your local machine can be a hassle—lengthy steps, OS-specific quirks, and potential conflicts. Luckily, Docker makes the process super simple, fast, and portable. Let’s walk through how to run PostgreSQL in a Docker container.

Why postgres in docker ?

You don’t need to install PostgreSQL directly on your system.
You can run multiple versions of PostgreSQL
Docker isolates the database from your host OS—less risk of breaking other things.

Install Docker Desktop

First you need to download docker desktop and install it and sign up. If you have already done this, you can skip this process. Please make sure docker desktop is running the entire process.

Running PostgreSQL Container

Open the terminal and run the command

docker run --name docker-postgres -e POSTGRES_PASSWORD=mypassword -p 5431:5432 -d postgres:16

Breakdown

--name : name stands for name of the container.
-e : e stands for environment variables. We are setting one environment POSTGRES_PASSWORD. POSTGRES_USER is assigned default to postgres. You can change it if you want using the same name env variable.
-d : d stands for detached mode.
postgres:16 : This is the image that will run. If postgres:16 image is already present , it will use that image. If not it will pull from the dockerhub.
-p 5431:5432: Maps port 5432 on your host (localhost) to port 5432 in the container. If you have PostgreSQL already installed locally, change the host port (e.g., -p 5431:5432) to avoid conflicts.
-e POSTGRES_DB=mydatabase : If this env is not added then default db with name postgres is created. If you want to name your database something else you can use this env.

After running this command, verify the container is running in Docker Desktop UI:

Check if docker container is running

docker ps

It should give you a list of all the container that are running right now. check for your container name.

Connect to postgres

Now in order to connect to postgreql running in docker container, run the command

docker exec -it docker-postgres psql -U postgres

Breakdown:

docker-postgres: your container name
psql: the command to run inside the container. psql comes with postgres image.
-U postgres: tells psql which user to connect as
-it : Runs the container in interactive mode and allocates a virtual terminal
exec : Execute a command inside a running container

How to create a new database.

If no POSTGRES_DB env is given while creating the container, you will be assigned the default database named postgres. If you want a new database, run the command

CREATE DATABASE outline_database;

How to check all the database inside the container

\l

Press q to exit the psql shell pager.

What's Next?

Now that you have PostgreSQL running inside Docker, you can:

Connect using a GUI like pgAdmin, TablePlus, or DBeaver.
Use it in your local dev projects.
Persist data using Docker volumes (explored in future posts