> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Pgrust with Docker - Drop-in Postgres Replacement

> Run Pgrust in Docker or Docker Compose. malisper/pgrust:v0.2 is a drop-in replacement for the official postgres image - same env vars and data volume.

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:

```bash theme={null}
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.        |

<Warning>
  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.
</Warning>

## Docker Compose

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

```yaml theme={null}
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:

```bash theme={null}
docker compose up -d
```

Check that the container is healthy:

```bash theme={null}
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.

<Tabs>
  <Tab title="psql">
    ```bash theme={null}
    psql -h localhost -U myuser -d mydb
    ```

    Or using a connection URL:

    ```bash theme={null}
    psql "postgresql://myuser:secret@localhost:5432/mydb"
    ```
  </Tab>

  <Tab title="Connection string">
    Use this connection string format in any driver or application:

    ```text theme={null}
    postgresql://myuser:secret@localhost:5432/mydb
    ```

    For apps that use keyword/value format:

    ```text theme={null}
    host=localhost port=5432 user=myuser password=secret dbname=mydb
    ```
  </Tab>

  <Tab title="psql (exec into container)">
    You can also connect directly from inside the running container without exposing the port:

    ```bash theme={null}
    docker exec -it pgrust psql -U myuser -d mydb
    ```
  </Tab>
</Tabs>

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

<Note>
  **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.
</Note>

<Warning>
  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.
</Warning>