01_postgres_with_docker

How postgres is used with docker

• Postgres Docker Container
• Postgres - Actual Postgres instance running inside the container.
• Psql - Powerful and lightweight command-line tool included in standard PostgreSQL distribution, therefore, available within the Postgres Docker Container
  • We will use psql from within the container to connect to the database and run sql commands.
• Terminal - Runs on host OS.
  • We will use this to spin up thePostgres container and then connect to the database using the psql tool.

Linux (Fedora)

Step 1: Create a volume for persistent storage

bash

sudo docker volume create postgres-volume

• Where is it stored?

sudo docker volume inspect postgres-volume

[
    {
        "CreatedAt": "2026-02-26T11:34:19+05:30",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/postgres-volume/_data",
        "Name": "postgres-volume",
        "Options": null,
        "Scope": "local"
    }
]

Step 2: Start a postgres container

• Start a db container named Postgres
• Environment Variables - Username and Password
• Maps container’s port to host’s port
• Mounts the volume
• Starts the container as a background process

bash

sudo docker run --name postgres \  
	-e POSTGRES_USER=abcd \  
	-e POSTGRES_PASSWORD=1234 \  
	-p 5432:5432 \  
	-v postgres-volume:/var/lib/postgresql/data \  
	-d postgres:17.2

Question : Does Postgres have a default user/password?

• Default User postgres
• Default Password : No
  • We must one provide via: -e POSTGRES_PASSWORD=secret . If we don’t, the container will refuse to start (unless we explicitly allow trust auth, which is insecure).

Question: What does POSTGRES_PASSWORD actually do?

bash

sudo docker run --name postgres \  
	-e POSTGRES_USER=abcd \  
	-e POSTGRES_PASSWORD=1234 \  
	-p 5432:5432 \  
	-v postgres-volume:/var/lib/postgresql/data \  
	-d postgres:17.2

This does:

• Creates a database cluster (if volume is empty)
• Creates a superuser named abcd
  • The default postgres role is NOT created unless you explicitly create it
  • If username is not provided then postgres becomes the default DB
• Sets its password to 1234

It is a database superuser. It can:

• Create databases
• Create roles
• Drop tables
• Bypass permissions
• Read/write any DB data

But it cannot:

• Access host system files
• Become system root
• Escape Docker

Question: What if Docker isn’t installed yet?

bash

sudo dnf install docker
sudo systemctl start docker
sudo systemctl enable docker   # auto-start on boot

• Check it’s working:

bash

sudo docker --version
sudo docker ps

Question: What if the container fails to start?

• Check what went wrong:

bash

sudo docker logs postgres

Common reasons:

• Port 5432 already in use (maybe a local postgres is running) → stop it: sudo systemctl stop postgresql
• Volume already has data from a different postgres version → wipe the volume or use a matching image version
• Name conflict → a container named postgres already exists (stopped) → sudo docker rm postgres

Question: How do I check if the container is running?

bash

sudo docker ps           # running containers
sudo docker ps -a        # all containers (including stopped)

Question: How do I connect to the running postgres?

Option 1 - from inside the container:

bash

sudo docker exec -it postgres psql -U abcd

Option 2 - from host machine (if psql is installed on host):

bash

psql -h localhost -p 5432 -U abcd

Option 3 - from another container on the same machine, use the container name as host:

bash

psql -h postgres -p 5432 -U abcd

(This only works if both containers are on the same Docker network)

Question: What if I forget the password?

• You can’t recover it easily. Best option is to wipe and recreate:

bash

sudo docker rm -f postgres
sudo docker volume rm postgres-volume
# then re-run with new credentials

• OR connect without password using trust auth temporarily (not recommended for production).

---

Using this container from the next time

STEP 1: Start/ Stop the same container

• Start

bash

sudo docker stop postgres

• Stop

bash

sudo docker start postgres

This uses the same container and the same mounted volume, so everything persists.

Question: Container stopped on its own / after reboot?

• Docker containers don’t auto-restart after a system reboot by default.
• Fix: add --restart unless-stopped when creating the container:

bash

sudo docker run --name postgres \  
	--restart unless-stopped \
	-e POSTGRES_USER=abcd \  
	-e POSTGRES_PASSWORD=1234 \  
	-p 5432:5432 \  
	-v postgres-volume:/var/lib/postgresql/data \  
	-d postgres:17.2

• Or for an already existing container:

bash

sudo docker update --restart unless-stopped postgres

• Also make sure Docker itself starts on boot:

bash

sudo systemctl enable docker

---

Using new container from next time

If we remove the container, the volume stays (unless we explicitly remove it).

• Remove container (data safe because it’s in the volume):

bash

sudo docker rm -f postgres

• Create a new container later reusing the same volume:

bash

sudo docker run --name postgres \  
-e POSTGRES_USER=abcd \  
-e POSTGRES_PASSWORD=1234 \  
-p 5432:5432 \  
-v postgres-volume:/var/lib/postgresql/data \  
-d postgres:17.2

Those POSTGRES_* env vars will be ignored if the volume already has a cluster. They’re basically “documentation” at that point, not configuration.

Question: What if I reuse a volume but change the postgres image version?

• Postgres does NOT auto-upgrade data between major versions (e.g. 15 → 17).
• The container will just fail to start and show an error in logs.
• You need to either stick to the same major version, or do a proper pg_dump → restore.

---

Complete Fresh Start

• If you want a completely new DB cluster (wipe everything):

bash

sudo docker rm -f postgres
sudo docker volume rm postgres-volume

Question: How do I take a backup before wiping?

bash

sudo docker exec -t postgres pg_dumpall -U abcd > backup.sql

• Restore later:

bash

cat backup.sql | sudo docker exec -i postgres psql -U abcd

---

Use Docker Compose

yaml

services:
  postgres:
    image: postgres:17.2
    container_name: postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: abcd
      POSTGRES_PASSWORD: "1234"
    volumes:
      - postgres-volume:/var/lib/postgresql/data
volumes:
  postgres-volume:

Start : sudo docker compose up -d

Stop: sudo docker compose down

Start again later : sudo docker compose up -d

The volume persists across down/up unless you add -v to down.

Wipe everything including volume:

bash

sudo docker compose down -v

Question: How to see container resource usage?

bash

sudo docker stats postgres

Question: How to list all volumes and clean up unused ones?

bash

sudo docker volume ls
sudo docker volume prune   # removes all volumes not attached to any container

Be careful with prune — it deletes data.