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 👀).In correct setup, the data gets lost only when you remove the container.

Let me know in the comments if you'd like a follow-up post on Docker volumes or connecting with pgAdmin!

Possible Error Troubleshooting

Error 1: OCI Runtime Exec Failed

Command causing error:

docker exec -it docker-postgres -U postgres

Error Message:

OCI runtime exec failed: exec failed: un   able to start container process: exec: "-U": executable file not found in $PATH: unknown

Solution:
The -U flag belongs to psql, not docker exec.

Correct Command:

docker exec -it docker-postgres psql -U postgres

Error 2: Database Creation Failed

Command causing error:

CREATE DATABASE outline-database

Error Message:

ERROR:  syntax error at or near "-"
LINE 1: CREATE DATABASE outline-database

Solutions:

1. Database names cannot contain hyphens (use underscores)
2. SQL commands require semicolon terminators

Correct Command:

CREATE DATABASE outline_database;