Connect to PostgreSQL running in Docker

For a host-side PostgreSQL client, publish the database's container port and connect to the corresponding host address. Another container on the same user-defined network can normally connect by container or service name without a host-port mapping.

Start a PostgreSQL 16 example

For local development, provide POSTGRES_PASSWORD through your shell environment rather than copying a literal password into the command:

: "${POSTGRES_PASSWORD:?Set a database initialization password}"
docker run -d --name pg \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_PASSWORD \
  -e POSTGRES_DB=mydb \
  --mount type=volume,source=pg-data,target=/var/lib/postgresql/data \
  postgres:16

Environment variables can still be visible through container inspection. For an appropriate secret-file workflow, the official image supports POSTGRES_PASSWORD_FILE. Use application roles with the necessary privileges rather than relying on the administrative postgres role for ordinary application traffic.

This mount path is for PostgreSQL 16's image layout. Official PostgreSQL 18+ images changed the default data-directory layout and volume target; check the selected tag's instructions before upgrading or changing mounts. A major-version upgrade is not simply a new tag against the old data directory.

Connect from the intended client

psql -h 127.0.0.1 -p 5432 -U postgres -d mydb

For a remote machine, publish on the intended reachable host interface instead of loopback and configure firewall, PostgreSQL access rules, and transport protection. Use that host address in the client. If port 5432 is occupied, map a different host port such as 127.0.0.1:15432:5432 and connect to 15432.

For container-to-container access, attach both services to a suitable user-defined network and use pg:5432. If pg already exists, docker network connect appnet pg can attach it to an existing network; do not try to create a second container with the same name. Applications still need readiness handling and valid database credentials.

Separate initialization from ongoing configuration

The official image's initialization variables apply when starting with an empty data directory. Changing POSTGRES_PASSWORD later does not reset a password in an initialized database. Change the role password through an authenticated PostgreSQL administration workflow; do not delete a populated volume just to repair credentials.

The image normally requires an initialization password or an explicitly configured alternative authentication method. That is different from saying the variable is required on every startup. Its declared volume can also create anonymous storage when you omit your own mount; explicit named storage makes reuse clearer, but neither form replaces backups.

Troubleshoot in layers

Check docker ps -a, docker logs pg, and docker port pg. A running container may still be initializing. Then verify listen_addresses, the matching pg_hba.conf rule, and credentials. PostgreSQL uses the first matching host-authentication rule; later rules do not serve as fallbacks after authentication fails.

Server parameters can be supplied after the image, for example postgres:16 -c max_connections=200, or through managed configuration. Parameters differ in whether they need reload or restart; review capacity before increasing limits.

For sustained monitoring, configure a dedicated account through Guance's PostgreSQL integration and test connectivity from the collector's own network. Application connectivity does not prove the collector has the right route or privileges.

See the official PostgreSQL image and PostgreSQL host authentication.