DockerコンテナからホストPostgreSQLへ接続する完璧ガイド：localhostの罠とネットワーク設定の秘訣

Posted at 2026-11-10

Dockerコンテナからホストマシン上のPostgreSQLへ接続しようとした際、Connection Refusedなどのエラーが発生して接続できないトラブルに直面する。原因は、コンテナ内のlocalhostがホスト側ではなくコンテナ自身を指してしまうネットワーク隔離の仕様にある。

何が起きたか（発生した症状と原因）

コンテナ内部からlocalhostや127.0.0.1宛てにデータベース接続を試みると、コンテナ自身のループバックアドレスを指してしまうため接続拒否される。
ホストOS側のPostgreSQLが、デフォルトで外部ネットワークやDockerブリッジからの接続を受け付けない設定になっている。
Docker DesktopとLinux環境で、ホストを指定する方法（マジックDNS名やIPアドレス）が異なるため混乱しやすい。

PostgreSQLの待ち受け設定と、Docker側のネットワーク設定を適切に結びつけることで解決する。例えば、Docker Compose v2+を利用したLinuxおよびMac/Windows共通の環境では、extra_hostsにhost-gatewayを指定するのが最も確実である。

services:
  app:
    environment:
      DB_HOST: db_host
    extra_hosts:
      - "db_host:host-gateway"

👉 PostgreSQL側のpostgresql.confやpg_hba.confの具体的な書き換え手順や、OSごとのホスト指定の差異について確認するにはこちら。
DockerコンテナからホストPostgreSQLへ接続する完璧ガイド：localhostの罠とネットワーク設定の秘訣

Before: 接続先IPやポートのハードコードに悩まされ、環境を変えるたびにアプリケーションの設定修正が必要だった。
After: host.docker.internalやhost-gatewayの活用により、OS差異を意識せずにポータブルで安全なホストDB接続が確立される。

Postgresの権限設定における172.17.0.0/16の指定方法や、Docker Desktop・Linuxそれぞれの環境における完全な設定ファイル全文の解説を確認するにはこちら。

※本記事は技術ブログ CodeArchPedia.com の執筆記事から要点を抜粋した技術ノートです。