issue with healthcheck on postgres/alpine 18.4

[hyperfocusedblur]

im runnning postgres alpine latest version in podman with podman-compose
here is my compose file:

volumes:
  pgdata:

services:
  db:
    image: docker.io/library/postgres:alpine
    container_name: postgres_container 
    env_file:
      - .env
    volumes:
      - pgdata:/var/lib/postgresql/data/pgdata
    healthcheck:
      test: ["CMD-SHELL", "pg_isready --dbname=${POSTGRES_DB} --username=${POSTGRES_USER}"]
      interval: 10s
      retries: 5
      timeout: 5s
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    shm_size: 128mb
    restart: unless-stopped

.env file

POSTGRES_USER=postgres_user
POSTGRES_PASSWORD=password
POSTGRES_DB=postgres_db

the issue:
healthcheck returns error and condition healthy never arrives. status of the container hangs on 'starting' if i use healtcheck in compose.
however if i manually run pg_isready on the container from host, there seems to be nothing that would indicate that something is 'not healthy'.

in logs, i see that healthcheck command is probably getting this FATAL value from the postgres container:

[db]     | 2026-05-23 13:22:14.761 UTC [1] LOG:  database system is ready to accept connections
[db]     | 2026-05-23 13:22:21.449 UTC [68] FATAL:  database "postgres_user" does not exist // this is when i manually call pg_isready from the host to the container
[db]     | 2026-05-23 13:22:30.899 UTC [70] FATAL:  database "postgres_user" does not exist

however when i run pg_isready from the host i receive this on stdout:

 $ podman exec postgres_container pg_isready -U postgres_user -d posgtres_db
/var/run/postgresql:5432 - accepting connections

also here it looks like the db exists, contrary to logs:

podman exec postgres_container psql -U postgres_user -l
                                                             List of databases
    Name     |     Owner     | Encoding | Locale Provider |  Collate   |   Ctype    | Locale | ICU Rules |        Access privileges
-------------+---------------+----------+-----------------+------------+------------+--------+-----------+---------------------------------
 postgres    | postgres_user | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           |
 postgres_db | postgres_user | UTF8     | libc            | en_US.utf8 | en_US.utf8 |        |           |

to me at least, it indicates that there is no error and the database exists. maybe i am missing something

[tianon]

See #1237, https://github.com/docker-library/faq#healthcheck, and https://github.com/docker-library/healthcheck/blob/master/postgres/docker-healthcheck

[barab00lka]

See #1237, https://github.com/docker-library/faq#healthcheck, and https://github.com/docker-library/healthcheck/blob/master/postgres/docker-healthcheck

thanks for the answer, that makes sense now. For some reason on many docker-compose.yml examples for postgres that i found on the web they all include the healthcheck

[Martzcode]

This is often caused by an environment variable expansion issue in the healthcheck script or compose configuration, combined with how PostgreSQL handles client connection attempts.

Why this happens

The log:

FATAL: database "root" does not exist

usually indicates that psql was run without specifying the database (-d or -U defaults), so it attempted to connect to a database named after the OS user running the command (often root in containers).

In the official postgres images, the entrypoint or healthcheck might run psql -U "$POSTGRES_USER" -d "$POSTGRES_DB". If these variables are not correctly resolved, or if a check is run directly from the host (e.g. docker exec) without passing the correct environment, it defaults to root.

How to fix it in your Compose file

Make sure your healthcheck definition explicitly passes the correct user and database:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
  interval: 10s
  timeout: 5s
  retries: 5

Note the double dollar sign $$: In docker-compose.yaml, you must use $$ so that the variables are evaluated inside the container by the shell, rather than on the host during the compose interpolation phase.

Alternatively, hardcode the default postgres user and database if you aren't changing them:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]

Checking if it's Podman-specific

If you are using podman-compose, it has a known issue where it doesn't always pass the environment variables properly to the healthcheck shell. In that case, using the explicit pg_isready -U postgres style test command without variables is the most robust workaround.

[tianon]

(and also --host 127.0.0.1 as noted in #920 (comment) and shown in https://github.com/docker-library/healthcheck/blob/master/postgres/docker-healthcheck)