gmarrot/postgresql-client repository overview

⁠PostgreSQL Client Images

Lightweight Docker images containing the PostgreSQL client (psql), based on Alpine Linux. Available in two variants: client only or client + Nginx.

⁠Available Variants

⁠Client Image (PostgreSQL client only)

Minimal image with only the PostgreSQL client for running psql, pg_dump, etc.

⁠Nginx Image (PostgreSQL client + Nginx)

Image combining Nginx with the PostgreSQL client, suitable for scenarios where both Nginx and PostgreSQL tools are needed in the same container (reverse proxy, API gateways, etc.).

⁠Supported Platforms

• linux/amd64
• linux/arm64

⁠Usage

⁠Run an interactive shell with the PostgreSQL client

docker run -it --rm gmarrot/postgresql-client:18 /bin/ash
# Then inside the container:
psql -h <host> -U <user> -d <database>

⁠Run a psql command directly

docker run --rm gmarrot/postgresql-client:18 psql -h postgres.example.com -U myuser -d mydb -c "SELECT version();"

⁠pg_dump from a remote database

docker run --rm gmarrot/postgresql-client:18 pg_dump -h postgres.example.com -U myuser -d mydb > backup.sql

⁠Nginx image (main process: Nginx)

docker run -d --name nginx-pg gmarrot/postgresql-client:18-nginx
# Nginx runs in the foreground. The psql client is available inside the container if you exec into it.

⁠Docker with Environment Variables

You can pass connection parameters to the container using PostgreSQL's environment variables, which allows psql and other client tools to connect without specifying -h, -U, -d on the command line.

⁠Using -e flags

docker run -it --rm \
  -e PGHOST=postgres.example.com \
  -e PGPORT=5432 \
  -e PGDATABASE=mydb \
  -e PGUSER=myuser \
  -e PGPASSWORD=mypassword \
  gmarrot/postgresql-client:18 psql -c "SELECT version();"

⁠Using an env file

# .env file
PGHOST=postgres.example.com
PGPORT=5432
PGDATABASE=mydb
PGUSER=myuser
PGPASSWORD=mypassword

# Run with --env-file
docker run -it --rm --env-file .env gmarrot/postgresql-client:18 psql

⁠Connecting to a PostgreSQL container on the same Docker network

docker run -it --rm \
  --network my-app-network \
  -e PGHOST=postgres \
  -e PGDATABASE=appdb \
  -e PGUSER=appuser \
  -e PGPASSWORD=secret \
  gmarrot/postgresql-client:18 psql

⁠Supported PostgreSQL Environment Variables

For a complete list, see the PostgreSQL libpq environment variables documentation⁠.

⁠Base Images

• Client: dhi.io/alpine-base
• Nginx: dhi.io/nginx

⁠License

MIT License. See LICENSE⁠ for details.