Fix Docker containers that cannot reach PostgreSQL on a VPS

A container that worked fine suddenly cannot connect to the PostgreSQL installed on the host? The usual cause: Docker reallocates its network IP range (dynamic allocation) whenever you run docker-compose down and up again, and PostgreSQL refuses the connection because the new IP is not on its allow list. This guide covers the diagnosis, the quick fix for the current subnet, and a one-time fix that covers every subnet. It applies to PostgreSQL 14/16 on an Ubuntu/Debian VPS running Docker.

Throughout, myapp is the example container name and myapp_default the example Docker network name - replace them with your own. Paths assume PostgreSQL 16; change 16 to match your version.

1. Why does Docker change the IP?

Think of Docker managing networks like a hotel assigning rooms:

• First run: you run docker-compose up for the myapp project. Docker sees that "Room 1" (172.17.x.x) is free and gives it to your project.
• Later on:
  1. You install another project (for example my-blog). It takes "Room 1" (172.17.x.x).
  2. Then you start the myapp project again (docker-compose up).
  3. Docker sees "Room 1" is occupied, so it automatically moves the project to "Room 2" (172.18.x.x) or "Room 3" (172.19.x.x).

The result: you had configured PostgreSQL to accept only "Room 1" (172.17.0.1). Now that the project lives in "Room 2" (172.18.0.1), PostgreSQL sees an unknown IP and blocks it immediately - and the connection error appears.

2. Diagnose: find the current IP and network name

Run this to see which IP the container received and which network it belongs to (replace myapp with your container name):

# With jq installed (nicer output)
docker inspect -f '{{json .NetworkSettings.Networks}}' myapp | jq .

# Without jq (use grep)
docker inspect myapp | grep -A 20 "Networks"

You are looking for two values:

3. Inspect the subnet and gateway

With the network name from step 2, run this to see how that network is laid out:

# Replace the network name with the one you found in step 2
docker network inspect myapp_default

The output includes a Config section like this:

"Config": [
    {
        "Subnet": "172.18.0.0/16",
        "Gateway": "172.18.0.1"
    }
]

4. Open the firewall (UFW)

Run this on the VPS so UFW lets the Docker subnet through to the PostgreSQL port (5432):

# Replace 172.21.0.0/16 with the subnet you found in step 3
sudo ufw allow from 172.21.0.0/16 to any port 5432
sudo ufw reload

5. Update the PostgreSQL config

5.1. Edit pg_hba.conf

# Locate the config file (usually /etc/postgresql/14/main/ or 16/main/)
sudo nano /etc/postgresql/16/main/pg_hba.conf

Add this line at the end of the file (adjust the subnet to yours):

# Allow Docker containers to connect to PostgreSQL
host    all             all             172.21.0.0/16           scram-sha-256

5.2. Check postgresql.conf

sudo nano /etc/postgresql/16/main/postgresql.conf

Find the listen_addresses line:

• If it is already listen_addresses = '*', there is nothing to change.
• If it lists individual IPs (the approach in Set up PostgreSQL on a VPS securely), you must add the Docker gateway to the list (for example ,172.21.0.1).

5.3. Restart PostgreSQL

sudo systemctl restart postgresql

6. Test again

Once PostgreSQL has restarted, restart the API container:

docker restart myapp

Check the logs to confirm the connection now succeeds:

docker logs myapp --tail 50

7. The silver bullet fix (recommended)

The better fix: grant access to the entire IP range Docker can use, once and for all.

The theory

Under RFC 1918, Docker is allowed to use the private class B IP range:

• From 172.16.0.0 to 172.31.255.255
• In CIDR notation: 172.16.0.0/12

Once 172.16.0.0/12 is allowed:

Step 1: Edit pg_hba.conf

sudo nano /etc/postgresql/16/main/pg_hba.conf

Add this line (or replace the old one):

# Silver bullet: allow any IP in the Docker range (172.16.x.x -> 172.31.x.x)
host    all             all             172.16.0.0/12           scram-sha-256

Step 2: Open the UFW firewall

sudo ufw allow from 172.16.0.0/12 to any port 5432
sudo ufw reload

Step 3: Restart PostgreSQL

sudo systemctl restart postgresql

Step 4: Update the connection string in your code

The connection string still has to point at the gateway IP of the current Docker network. The gateway is always .1 of the subnet:

Quick summary

# 1. Find the container's network name and IP
docker inspect myapp | grep -A 20 "Networks"

# 2. Inspect the subnet and gateway
docker network inspect <network-name>

# 3. Open the firewall (silver bullet - do it once)
sudo ufw allow from 172.16.0.0/12 to any port 5432
sudo ufw reload

# 4. Edit pg_hba.conf - add this line:
# host    all    all    172.16.0.0/12    scram-sha-256

# 5. Restart PostgreSQL
sudo systemctl restart postgresql

# 6. Restart the container
docker restart myapp

Troubleshooting