Configuring Docker Container Connections to Local PostgreSQL Database: Network Principles and Implementation

Problem Context and Core Challenges

Connecting Docker containers to host-local databases presents significant technical challenges in containerized application development. Users frequently encounter "Connection refused" errors when attempting to connect QGIS Docker containers to local PostgreSQL instances, indicating network connectivity barriers. These issues typically stem from mismatches between Docker's network isolation features and PostgreSQL's access control configurations.

Docker Network Architecture Analysis

Docker automatically creates a docker0 bridge network interface, typically assigned to the 172.17.0.0/16 subnet. Network configuration can be inspected using the ip a command:

$ ip a
...
3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN 
    link/ether 56:84:7a:fe:97:99 brd ff:ff:ff:ff:ff:ff
    inet 172.17.42.1/16 scope global docker0
       valid_lft forever preferred_lft forever

Each Docker container receives a randomly assigned IP address within this subnet, enabling network isolation between containers while complicating communication with host services.

PostgreSQL Configuration Optimization

Enabling container access to PostgreSQL requires multi-layered configuration adjustments. First, modify PostgreSQL's listening address configuration in the postgresql.conf file:

listen_addresses = '*'

This configuration allows PostgreSQL to listen for connection requests on all available network interfaces, rather than being restricted to local loopback addresses.

Access Control Configuration

The pg_hba.conf file governs PostgreSQL client authentication. A common misconfiguration involves using 172.17.0.0/32, which actually represents only the single IP address 172.17.0.0. The correct configuration should use:

host    all             all             172.17.0.0/16            md5

172.17.0.0/16 represents the entire Docker default subnet, ensuring all containers within this range can pass authentication.

Connection Strategy Selection

When connecting to databases from within containers, avoid using localhost and instead use the host's actual IP address. To maintain configuration flexibility, add host mapping via the --add-host parameter:

docker run --add-host=database:172.17.42.1 my-container

In application configurations, use database as the database hostname, ensuring container configurations remain unchanged even if host IP addresses change.

Cross-Platform Solutions

Different operating system environments offer specific solutions. In Docker Desktop for Mac environments, utilize the built-in host.docker.internal domain:

docker run -e DB_HOST=host.docker.internal my-app

For Linux environments, directly use the Docker bridge network gateway address 172.17.0.1. In certain scenarios, using the --network=host parameter allows containers to share the host's network namespace, though this sacrifices some container isolation.

Configuration Verification and Troubleshooting

Post-configuration system validation is essential. First, confirm PostgreSQL service is running normally:

sudo systemctl status postgresql

Test network connectivity:

docker exec -it container-name ping 172.17.42.1

Check port accessibility:

telnet 172.17.42.1 5432

Analyze connection issues through system logs:

sudo tail -f /var/log/postgresql/postgresql-9.3-main.log

Security Considerations

Network access openness requires careful security consideration. Strong password authentication is recommended over trust mode, with regular updates to access control lists and restrictions on unnecessary IP range access. In production environments, dedicated networks or VPN tunnels should be considered to ensure data transmission security.

Conclusion

The core of Docker container connectivity to local databases lies in understanding network architecture and correctly configuring access controls. Through proper setup of PostgreSQL listening addresses, access control rules, and container network parameters, stable and reliable connections can be established. Best practices vary across different environments, requiring developers to select the most appropriate solutions based on specific scenarios.