Fixing “Connection Refused” Error Between pgAdmin and Postgres in Docker

When setting up pgAdmin to connect with PostgreSQL in a Docker environment, a common issue developers encounter is the “Connection Refused” error. This error typically arises due to incorrect configuration of the connection parameters in pgAdmin, particularly when using service names rather than container names.

In this article, we’ll walk through the steps to resolve the “Connection Refused” error by ensuring that pgAdmin connects to PostgreSQL using the container name.

Understanding the Problem

Docker containers use an internal network for communication, and each container can be accessed using its container name as the hostname. If you’re trying to connect pgAdmin to a PostgreSQL container and using localhost or an IP address, the connection will fail because pgAdmin doesn’t know where to find the PostgreSQL instance in the Docker network.

The error might look something like this in the logs:

could not connect to server: Connection refused
    Is the server running on host "localhost" and accepting
    TCP/IP connections on port 5432?

This happens because pgAdmin is not able to resolve localhost or the specified IP to the PostgreSQL container. The solution is to use the PostgreSQL container name in the connection settings.

Steps to Fix pgAdmin and PostgreSQL Connection in Docker

1. Set Up docker-compose.yml

Ensure that both pgAdmin and Postgres are part of the same Docker Compose network. Here’s a basic configuration:

version: '3'
services:
  postgres:
    image: postgres:14
    container_name: postgresdb
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydatabase
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  pgadmin:
    image: dpage/pgadmin4
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: admin
    ports:
      - "8080:80"
    depends_on:
      - postgres  # Ensures pgAdmin starts after PostgreSQL
    networks:
      - pgnetwork

networks:
  pgnetwork:
    driver: bridge

volumes:
  postgres_data:

In this example, PostgreSQL is running inside a container named postgresdb, and pgAdmin runs in another container called pgadmin. Both containers are connected via a Docker network named pgnetwork.

1. Access pgAdmin and Add a New Server

After running docker-compose up, pgAdmin will be accessible at http://localhost:8080. Use the credentials you specified (admin@admin.com and admin).

To connect pgAdmin to PostgreSQL:
a. Open pgAdmin in your browser.
b. Click on Add New Server.
c. In the General tab, name your server anything you like, e.g., “Postgres DB”.
d. In the Connection tab, use the following settings:

• Host name/address: postgresdb (this is the container name of your Postgres service in Docker)
• Port: 5432 (the default Postgres port)
• Username: admin (this is the POSTGRES_USER defined in the docker-compose.yml)
• Password: password (this is the POSTGRES_PASSWORD defined in the docker-compose.yml)
• Maintenance database: mydatabase (this is the POSTGRES_DB defined in the docker-compose.yml)

1. Understanding Why It Works

By using the container name (postgresdb) in the Host name/address field, you’re telling pgAdmin to resolve the PostgreSQL service via Docker’s internal DNS. This eliminates the need for localhost or any external IP addresses.

The depends_on field in docker-compose.yml ensures that pgAdmin does not start until the Postgres container is up and running, avoiding potential timing issues that might cause connection failures.

1. Troubleshooting Tips

• Firewall/Port Blocking: Ensure that port 5432 (Postgres) and port 8080 (pgAdmin) are open and not blocked by any firewall or security settings on your machine.
• Database Logs: If you’re still experiencing issues, check the logs of both the Postgres and pgAdmin containers by running:

docker-compose logs postgres
docker-compose logs pgadmin

These logs will provide insights into any errors or warnings that can guide your debugging.

• Network Inspection: You can inspect the Docker network to verify that both containers are connected and accessible by running:

docker network inspect <network_name>

In our case, it would be docker network inspect pgnetwork.

1. Testing the Connection

After completing the steps, test the connection by clicking Save in the pgAdmin interface. If everything is configured correctly, you should see your new server and be able to expand the database tree to view tables, schemas, and other details.

Conclusion

To resolve the “Connection Refused” error between pgAdmin and PostgreSQL when using Docker, make sure to:

• Use the Postgres container name (not localhost or an IP) in the pgAdmin server configuration.
• Ensure both services are connected via the same Docker network.
• Verify that the docker-compose.yml file is properly configured.

By following these steps, you’ll have pgAdmin connecting to your Postgres instance smoothly within the Docker environment.