Run Pgrust with Docker - Drop-in Postgres Replacement

The malisper/pgrust:v0.2 Docker image is a drop-in replacement for the official postgres image. It accepts the same environment variables, exposes the same port, and stores data in the same default location - so you can swap it into any existing Docker or Docker Compose setup by changing a single line. The image is multi-arch and supports both amd64 (x86-64) and arm64 (Apple Silicon, AWS Graviton) without any additional configuration.

Quick Start

Start a Pgrust container with a single command:

docker run -d \
  --name pgrust \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  malisper/pgrust:v0.2

Pgrust is now listening on localhost:5432. Connect immediately with psql or any PostgreSQL client.

Environment Variables

malisper/pgrust recognizes the same environment variables as the official postgres image. No new variables to learn.

Variable	Required	Default	Description
`POSTGRES_PASSWORD`	Yes	-	Superuser password for the default `postgres` (or `POSTGRES_USER`) account.
`POSTGRES_USER`	No	`postgres`	Name of the superuser account created on first start.
`POSTGRES_DB`	No	same as `POSTGRES_USER`	Name of the default database created on first start.
`PGDATA`	No	`/var/lib/postgresql/data`	Path inside the container where the data directory is stored.
`POSTGRES_INITDB_ARGS`	No	-	Additional arguments forwarded to `initdb` during initialization.
`POSTGRES_HOST_AUTH_METHOD`	No	`scram-sha-256`	Authentication method written to `pg_hba.conf` for host connections.

Setting POSTGRES_HOST_AUTH_METHOD=trust disables password authentication entirely. Do not use trust in any environment where the port is reachable by untrusted users.

Docker Compose

Drop Pgrust into a Compose stack the same way you would use the official postgres image:

services:
  db:
    image: malisper/pgrust:v0.2
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_USER: myuser
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Start the stack:

docker compose up -d

Check that the container is healthy:

docker compose ps
docker compose logs db

Connecting to the Container

Use any standard PostgreSQL client or driver. The connection details match whatever you configured in the environment variables.

psql
Connection string
psql (exec into container)

psql -h localhost -U myuser -d mydb

Or using a connection URL:

psql "postgresql://myuser:secret@localhost:5432/mydb"

Use this connection string format in any driver or application:

postgresql://myuser:secret@localhost:5432/mydb

For apps that use keyword/value format:

host=localhost port=5432 user=myuser password=secret dbname=mydb

You can also connect directly from inside the running container without exposing the port:

docker exec -it pgrust psql -U myuser -d mydb

Because Pgrust is 100% wire-compatible with PostgreSQL 18.3, every standard client works: psql, pgAdmin, TablePlus, DBeaver, DataGrip, and all language drivers (psycopg2, node-postgres, pgx, sqlx, JDBC, and more).

Multi-Arch Support

The malisper/pgrust:v0.2 image is a multi-platform manifest that includes:

Platform	Architecture
`linux/amd64`	x86-64 (Intel / AMD)
`linux/arm64`	ARM64 (Apple Silicon via Docker Desktop, AWS Graviton, etc.)

Docker automatically pulls the correct variant for your host. No --platform flag is needed.

Limitations

PostgreSQL extensions (.so files) are not supported. Pgrust does not yet have a stable extension ABI, so existing compiled extensions cannot be loaded. Built-in functionality — including the bundled pgrcolumnar columnar storage engine — works normally. Pure-SQL extensions that do not rely on a shared library may work, but are not officially tested.

Pgrust v0.2 is not yet production-ready. Do not use this image to store data you cannot afford to lose. It is intended for evaluation, benchmarking, and development.

​Quick Start

​Environment Variables

​Docker Compose

​Connecting to the Container

​Multi-Arch Support

​Limitations

Quick Start

Environment Variables

Docker Compose

Connecting to the Container

Multi-Arch Support

Limitations