Introduction PostgreSQL is a powerful, open-source object-relational database system. It is a highly scalable, SQL-compliant database management system that is used to handle large workloads. PostgreSQL is a popular choice for many developers and organizations due to its robust features, extensibility, and reliability.

Installing PostgreSQL directly on your local machine can be a difficult and also take multiple steps, configuration issues, and potential conflicts with other software. This process is especially cumbersome on Windows. Fortunately, Docker provides a much simpler, faster, and more portable solution. Let’s go through how to set up and run PostgreSQL inside a Docker container.

Before Docker

1. You must install PostgreSQL locally, configure paths, users, and ports manually.
2. Resetting the database means manually dropping tables or reinstalling.
3. Different projects may need different PostgreSQL versions — hard to manage on one system.
4. Config files, logs, and data clutter your OS. Uninstalling doesn’t clean everything.
5. Every team member must install and configure PostgreSQL the same way.

After Docker

1. One docker-compose up and you have a running PostgreSQL instance.
2. Just docker down and docker up to reset everything.
3. You can switch PostgreSQL versions by changing one line in your config.
4. Everything runs inside a container — no system pollution.
5. Easily link PostgreSQL with backend services (Node.js, Django, etc.) in one Compose file.

Prerequisites Before you begin, you will need to have the following prerequisites:

A system running Windows Docker installed on your system Basic knowledge of using the command line

Installing Docker

If you doesn’t have Docker installed on your Windows, you can download and install it from the official Docker website. Follow the instructions provided on the website step by step to install Docker on your Windows.

Once the docker is installed, you can verify the installation by running:

docker --version

This command will display the version of Docker installed on your system.

To create a PostgreSQL environment in Docker you can choose between two approaches GUI-based or terminal-based. Let’s start with GUI-based method first.

Create Folder

Create a new folder to store your PostgreSQL data. This folder will be used to store the data files for your PostgreSQL instance. Usually keep this directory in your project folder so that it is easy to manage.

Docker Compose File

Create a new file named compose.yml in the same folder. This file will contain the configuration for your PostgreSQL container.

Insert the following content into the compose.ymlfile:

services:
db:
image: postgres:alpine
container_name: postgres
restart: always
environment:
POSTGRES_DB: ${DB_NAME}
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
ports:
- ${DB_PORT}:5432  # Ensure no other service is using this port
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $${DB_NAME} -U $${DB_USER}"]
interval: 10s
timeout: 30s
retries: 5
volumes:
- ./data/db:/var/lib/postgresql/data

pgadmin:
image: dpage/pgadmin4
container_name: pgadmin
restart: always
environment:
PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
ports:
- 8080:80  # Access pgAdmin at http://localhost:8080
depends_on:
- db

This configuration defines two services: db and pgAdmin. The db service runs a PostgreSQL instance using the official Docker image, with data stored in ./data/db. It exposes port 5432 and uses environment variables to set the database name, user, and password.

The pgAdmin service uses the dpage/pgadmin4 image to provide a web-based PostgreSQL management interface. It maps port 8080 on the host to port 80 in the container, letting you access pgAdmin at http://localhost:8080 using the credentials defined in the environment file.

If you want a fast, portable, and minimal tool to manage multiple databases — especially in Docker or lightweight environments. Can use these code

adminer:
image: adminer
container_name: adminer
restart: always
ports:
- 8080:8080

replace pgadmin code with adminer code .

Environment Variables To configure the database name, username, and password, create a .env file in the same directory as your docker-compose.yml file and add the following content:

DB_NAME=test-db
DB_USER=testuser
DB_PASSWORD=userpass
DB_PORT=5432
# Use PGADMIN_EMAIL and PGADMIN_PASSWORD only if you’re using pgAdmin.
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=adminpass

Replace the values with your preferred database name, username, and credentials.

Start the Container Run the following command to start PostgreSQL and the chosen management tool(s):

docker compose up -d

This command will pull the necessary Docker images and start PostgreSQL, pgAdmin, and/or Adminer in the background. You can verify that the containers are running by executing the following command:

docker ps

You should see postgres, pgadmin, and/or adminer listed in the output.

Access the Web Interfaces

You can choose between pgAdmin or Adminer, depending on your preference: by opening a web browser and navigating to http://localhost:8080. In the login page, enter the database name, username, and password that you specified in the compose.yml file. You should now be able to interact with your PostgreSQL database through the Adminer or pgAdmin web interface.

Connect with PostgreSQL To connect with database url, you can use the following url:

postgresql://testuser:userpass@localhost:5432/test-db

That’s it! You’ve successfully set up PostgreSQL using Docker on your system.

Let’s start with terminal-based method

Step 1: Download the PostgreSQL Image Download the PostgreSQL image from Docker Hub at docker Hub

docker pull postgres

Step 2: Create a PostgreSQL Container Start creating a container with the following command:

docker run --name test-db -e POSTGRES_PASSWORD=userpass -d -p 5432:5432 postgres

• “test-db” is the name of the container (you can choose a different name if you prefer).
• “userpass” is the password you want to set for the “postgres” user in PostgreSQL.
• The “-d” option runs the container in the background.
• The “-p 5432:5432” option maps port 5432 from the container to port 5432 on the host, allowing you to connect to PostgreSQL from the host.

*Step 3: Download pgAdmin * Let’s download the pgAdmin image from Docker Hub

docker pull dpage/pgadmin4

Afterward, you need to create a container for running pgAdmin using the code:

docker run --name testuser -p 15432:80 -e "PGADMIN_DEFAULT_EMAIL=my_email@test.com" -e "PGADMIN_DEFAULT_PASSWORD=userpass" -d dpage/pgadmin4

• “testuser” is the name of the container being created.
• The “-p 15432:80” option maps port 15432, which is used for communication with pgAdmin, to port 80.
• “PGADMIN_DEFAULT_EMAIL” will be the login you use to access pgAdmin.
• “PGADMIN_DEFAULT_PASSWORD” will be the password you use to access pgAdmin.

You can access pgAdmin at https://localhost:15432, and you will see the pgAdmin interface.

Summary That’s it! You’ve successfully set up PostgreSQL using Docker — through both GUI (Docker Compose) and terminal-based methods. With this setup, you can easily manage databases, switch PostgreSQL versions, and connect your applications — all without cluttering your local system.