Skip to main content

Getting Started with PostgreSQL on Docker

Let's quickly set up a PostgreSQL database using Docker. This guide walks you through everything — from installation to running queries.

🛠 Prerequisites​

Ensure you have Docker installed:

Verify installation:

docker --version

If Docker is installed, you're ready to roll! 🎉

🔧 Step 1: Pull the PostgreSQL Docker Image​

Let's grab the official Postgres image from Docker Hub:

docker pull postgres

To pull a specific version (e.g., PostgreSQL 16):

docker pull postgres:16

🛠️ Step 2: Run a PostgreSQL Container​

Run the container with environment variables for user, password, and database name:

docker run -d \
  --name postgres-container \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=mydatabase \
  -p 5432:5432 \
  postgres

Explanation:​

  • -d: Run in detached mode (background)
  • --name: Name your container
  • -e: Set environment variables (user, password, database)
  • -p 5432:5432: Map local port 5432 to the container's 5432

✅ Check if it's running:

docker ps

💻 Step 3: Connect to PostgreSQL​

Let's connect to the running Postgres container:

docker exec -it postgres-container psql -U admin -d mydatabase

You should see the Postgres prompt:

mydatabase=#

🎉 Run your first query​

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL
);

INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');

SELECT * FROM users;

📦 Step 4: Persistent Data (Volumes)​

By default, Docker containers lose data when stopped. Let's fix that using volumes:

docker run -d \
  --name postgres-container \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=mydatabase \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  postgres

This mounts the database files to a persistent Docker volume named pgdata.

✅ Verify volume:

docker volume ls

🔥 Step 5: Docker Compose Setup (Optional)​

For easier setup, create a docker-compose.yml file:

version: '3.8'

services:
  db:
    image: postgres
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydatabase
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Start everything with:

docker-compose up -d

🛑 Stopping & Cleaning Up​

To stop and remove the container:

docker stop postgres-container

docker rm postgres-container

To remove the image (optional):

docker rmi postgres

🎯 Conclusion​

You've successfully set up PostgreSQL using Docker — faster, cleaner, and more portable than a manual install. Now, you can integrate it into your projects or connect it to an application.

🔗 Next steps:

  • Set up backups with pg_dump