How to Connect to PostgreSQL in a Docker Container from Outside

Docker makes it easy to isolate and run databases like PostgreSQL in containers. But one common question developers face is:
“How do I connect to my PostgreSQL container from outside—such as from a host machine or another app?”

In this blog post, we’ll walk through the steps to expose PostgreSQL running in a Docker container and access it using standard PostgreSQL clients from outside the container.

Table of Contents

🧠 Prerequisites

Docker installed and running on your machine.
A PostgreSQL Docker image or container running.
(Optional) A PostgreSQL client on your host machine (like psql, DBeaver, pgAdmin, etc.)

✅ Step 1: Start PostgreSQL Container with Port Mapping

To access PostgreSQL from outside the container, you must expose the container’s port to the host using the -p flag.

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

Explanation:

-p 5432:5432 maps container port 5432 (PostgreSQL default) to host port 5432.
Environment variables configure the initial database setup.

✅ Step 2: Check That PostgreSQL Is Running

Verify that the container is running:

docker ps

You should see postgres listed, and the PORTS column should show something like 0.0.0.0:5432->5432/tcp.

✅ Step 3: Connect from Host Using a Client

Now you can connect from your host machine using any PostgreSQL client.

🔹 Using `psql` CLI:

psql -h localhost -p 5432 -U admin -d mydb

When prompted, enter the password (secret in our example).

🔹 Using GUI (pgAdmin, DBeaver, etc.):

Host: localhost
Port: 5432
Username: admin
Password: secret
Database: mydb

🔐 Step 4: Allow Remote Connections (Optional for Network Access)

If you want to connect from other machines (not just localhost), you’ll need to:

A. Change the Host Mapping

docker run -d \
  --name my-postgres \
  -p 0.0.0.0:5432:5432 \
  ...

OR just use:

-p 5432:5432

This binds the container port to all interfaces.

B. Modify PostgreSQL Configuration (Inside Container)

Edit postgresql.conf (to listen on all IPs): Inside the container: docker exec -it my-postgres bash echo "listen_addresses = '*'" >> /var/lib/postgresql/data/postgresql.conf
Edit pg_hba.conf (to allow external clients): echo "host all all 0.0.0.0/0 md5" >> /var/lib/postgresql/data/pg_hba.conf
Restart the container: docker restart my-postgres

⚠️ Important Security Note: This makes PostgreSQL accessible to anyone on the network. For production, restrict IPs and enforce SSL connections.

🧪 Troubleshooting Tips

✅ Make sure the container is running (docker ps).
✅ Confirm the correct port is exposed using docker inspect.
✅ Use telnet localhost 5432 or netstat to check if the port is open.
🔐 Ensure your firewall allows connections on port 5432.

🧩 Alternative: Docker Compose Setup

Using docker-compose.yml to manage PostgreSQL:

version: '3.8'
services:
  db:
    image: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb

Then start with:

docker-compose up -d

Connect as usual from localhost:5432.

📝 Summary

Task	Command/Action
Start PostgreSQL with port exposed	`docker run -p 5432:5432 ... postgres`
Connect via CLI	`psql -h localhost -U user -d dbname`
Allow remote access	Modify `postgresql.conf` + `pg_hba.conf`
Use Docker Compose	Define `ports` in `docker-compose.yml`

Conclusion

Connecting to PostgreSQL running inside a Docker container is simple once you understand Docker’s port mapping. Whether you’re using it for development or running it on a server, exposing port 5432 and configuring security settings properly ensures smooth and secure database access from outside the container.