> ## 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.

# Get Started with Pgrust on macOS and Linux

> Install and run the Pgrust server on macOS or Linux in under 5 minutes. Download the binary, set environment variables, and connect with psql.

Pgrust ships as a pre-built binary that replaces the standard `postgres` server executable. Because it is 100% wire-compatible with PostgreSQL 18.3, you use the existing PostgreSQL client tools — `initdb`, `psql`, and any Postgres driver — to initialize, manage, and query it. The steps below get you from zero to a running server in under five minutes.

<Note>
  Prefer containers? See the [Docker guide](/docker) to run Pgrust with a single `docker run` command — no client tools required.
</Note>

## Install and Run

<Tabs>
  <Tab title="macOS (Apple Silicon)">
    <Steps>
      <Step title="Install PostgreSQL 18 client tools">
        Pgrust reuses the standard PostgreSQL `initdb` and `psql` utilities. Install them via Homebrew. Because `postgresql@18` is a keg-only formula, Homebrew does not put its binaries on your `PATH` automatically - you must export the path yourself:

        ```bash theme={null}
        brew install postgresql@18
        export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
        ```

        You do not need to start the Homebrew-managed PostgreSQL service. Only the client tools are required.
      </Step>

      <Step title="Download the Pgrust binary">
        Download the latest pre-built binary and verify its checksum. Using `curl` (rather than a browser download) avoids macOS Gatekeeper quarantine flags:

        ```bash theme={null}
        curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64
        curl -LO https://pgrust.com/downloads/v0.2/pgrust-0.2-macos-arm64.sha256
        shasum -a 256 -c pgrust-0.2-macos-arm64.sha256
        chmod +x pgrust-0.2-macos-arm64
        ```

        <Note>
          **macOS Gatekeeper:** the binaries are not yet Apple-notarized. If you download with a browser instead of `curl`, macOS may block execution. Clear the quarantine flag with:

          ```bash theme={null}
          xattr -d com.apple.quarantine pgrust-0.2-macos-arm64
          ```

          Or approve the binary under **System Settings → Privacy & Security → Open Anyway**.
        </Note>

        **Intel Mac:** use `pgrust-0.2-macos-x86_64` in place of `pgrust-0.2-macos-arm64`. A universal binary (`pgrust-0.2-macos-universal`) covering both architectures is also available.
      </Step>

      <Step title="Set required environment variables">
        Pgrust reads PostgreSQL's shared data files (timezone data, error messages, etc.) at runtime. Without these two variables it looks in `/usr/local/pgsql/share` and refuses to start:

        ```bash theme={null}
        export PGRUST_PGSHAREDIR="$(brew --prefix postgresql@18)/share/postgresql"
        export PGRUST_TZDIR="$PGRUST_PGSHAREDIR/timezone"
        ```

        <Tip>
          Add these lines (and the `PATH` export from Step 1) to your shell profile (`~/.zshrc` or `~/.bash_profile`) so they are set automatically in every new session.
        </Tip>
      </Step>

      <Step title="Initialize a data directory">
        Use the standard `initdb` tool to create and initialize a PostgreSQL data directory:

        ```bash theme={null}
        initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres
        ```
      </Step>

      <Step title="Start the Pgrust server">
        Start the server in the foreground. The `ulimit` and `RUST_MIN_STACK` settings prevent stack overflows on deep query plans:

        ```bash theme={null}
        ulimit -s 65520
        RUST_MIN_STACK=33554432 ./pgrust-0.2-macos-arm64 \
          -D /tmp/pgrust-data \
          -k /tmp -p 5432 \
          -c listen_addresses= \
          -c io_method=sync \
          -c max_stack_depth=60000
        ```

        You should see startup log output similar to a standard PostgreSQL server. The server listens on the Unix socket `/tmp/.s.PGSQL.5432`.
      </Step>

      <Step title="Connect with psql and run a test query">
        Open a second terminal. Re-export the `PATH` if you haven't added it to your profile, then connect via the Unix socket:

        ```bash theme={null}
        export PATH="$(brew --prefix postgresql@18)/bin:$PATH"
        psql -h /tmp -p 5432 -U postgres -c "select version()"
        ```

        You should see `pgrust 0.2 (PostgreSQL 18.3 compatible)`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Linux (Debian / Ubuntu)">
    <Steps>
      <Step title="Install PostgreSQL 18 client tools">
        Install `initdb` and `psql` from the official PostgreSQL Global Development Group (PGDG) APT repository. On Debian and Ubuntu, `initdb` ships in the `postgresql-18` server package and is not placed on `PATH` by default — export it manually:

        ```bash theme={null}
        sudo apt-get update
        sudo apt-get install -y curl ca-certificates gnupg
        sudo install -d /usr/share/postgresql-common/pgdg
        sudo curl -fsSL -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
          https://www.postgresql.org/media/keys/ACCC4CF8.asc
        echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
          http://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg main" \
          | sudo tee /etc/apt/sources.list.d/pgdg.list
        sudo apt-get update
        sudo apt-get install -y postgresql-18 postgresql-client-18
        export PATH="/usr/lib/postgresql/18/bin:$PATH"
        ```
      </Step>

      <Step title="Download the Pgrust binary">
        Set your platform and download the binary with checksum verification:

        ```bash theme={null}
        PLATFORM=linux-x86_64    # or: linux-aarch64

        curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM"
        curl -LO "https://pgrust.com/downloads/v0.2/pgrust-0.2-$PLATFORM.sha256"
        sha256sum -c "pgrust-0.2-$PLATFORM.sha256"
        chmod +x "pgrust-0.2-$PLATFORM"
        ```
      </Step>

      <Step title="Set required environment variables">
        Pgrust reads PostgreSQL's shared data files at runtime. On Debian/Ubuntu, Postgres is built against the system `tzdata`, so `PGRUST_TZDIR` points to the system zoneinfo directory:

        ```bash theme={null}
        export PGRUST_PGSHAREDIR=/usr/share/postgresql/18
        export PGRUST_TZDIR=/usr/share/zoneinfo
        ```

        <Tip>
          Add these lines and the `PATH` export to `~/.bashrc` or `/etc/environment` so they persist across sessions and reboots.
        </Tip>
      </Step>

      <Step title="Initialize a data directory">
        Use `initdb` to create and initialize a data directory:

        ```bash theme={null}
        initdb -D /tmp/pgrust-data --no-locale --encoding UTF8 -U postgres
        ```
      </Step>

      <Step title="Start the Pgrust server">
        Start the server in the foreground:

        ```bash theme={null}
        ulimit -s 65520
        RUST_MIN_STACK=33554432 "./pgrust-0.2-$PLATFORM" \
          -D /tmp/pgrust-data \
          -k /tmp -p 5432 \
          -c listen_addresses= \
          -c io_method=sync \
          -c max_stack_depth=60000
        ```

        The server listens on the Unix socket `/tmp/.s.PGSQL.5432`.
      </Step>

      <Step title="Connect with psql and run a test query">
        Open a second terminal and connect:

        ```bash theme={null}
        psql -h /tmp -p 5432 -U postgres -c "select version()"
        ```

        You should see `pgrust 0.2 (PostgreSQL 18.3 compatible)`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Managing the Server

* **Stop** with `Ctrl-C` in the server terminal, or `kill -INT <pid>`. This triggers PostgreSQL's fast shutdown and is safe.
* **Restart** by re-running the same server command against the same data directory. Your data is preserved across restarts.
* **Start over** by deleting the data directory: `rm -rf /tmp/pgrust-data`. This permanently deletes all data in it.

### Troubleshooting

<Note>
  **`FATAL: lock file "/tmp/.s.PGSQL.5432.lock" already exists`** — another server (likely an existing Postgres install) is already using port 5432. Start Pgrust on a different port:

  ```bash theme={null}
  # add -p 5433 to the server command, then connect with:
  psql -h /tmp -p 5433 -U postgres -c "select version()"
  ```

  After connecting, always run `SELECT version()` to confirm you are talking to Pgrust and not a background Postgres instance.
</Note>

<Note>
  **`could not open directory "/usr/local/pgsql/share/timezone"`** — the `PGRUST_PGSHAREDIR` and `PGRUST_TZDIR` environment variables are not set in the shell running the server. Re-export them before starting.
</Note>

## Using Other PostgreSQL Clients

Because Pgrust is 100% wire-compatible with PostgreSQL 18.3, **any standard PostgreSQL client or driver works without modification**:

* **GUI tools:** pgAdmin, TablePlus, DBeaver, DataGrip
* **Language drivers:** `libpq`, `psycopg2` / `psycopg3` (Python), `node-postgres` / `pg` (Node.js), `pgx` / `lib/pq` (Go), `diesel` / `sqlx` (Rust), JDBC (Java)
* **ORMs:** SQLAlchemy, Prisma, ActiveRecord, Hibernate, GORM

Use the standard PostgreSQL connection string format:

```text theme={null}
postgresql://username:password@localhost:5432/dbname
```

No special drivers, extensions, or configuration changes are needed on the client side.

## Advanced: stdio-wire Transport

The `postgres` binary exposes a `--stdio-wire` flag that routes the PostgreSQL wire protocol over `stdin`/`stdout` instead of a network socket. This is an advanced transport used internally for the WebAssembly browser demo and differential testing. You do not need it for normal local or networked usage.

## Building from Source

If you prefer to compile Pgrust yourself, or are targeting a platform without a pre-built binary, you can build from source. Rust 1.96.0 is pinned via `rust-toolchain.toml` and fetched automatically by `rustup` — you do not need to install a specific version manually.

<Steps>
  <Step title="Install build dependencies">
    Pgrust depends on Google's RE2 regular expression library. Release builds refuse to compile without it on purpose — a build using only the fallback regex engine is drastically slower on regex-heavy workloads.

    <CodeGroup>
      ```bash macOS theme={null}
      brew install re2 pkg-config
      ```

      ```bash Ubuntu / Debian theme={null}
      sudo apt-get install -y build-essential pkg-config libre2-dev
      ```
    </CodeGroup>
  </Step>

  <Step title="Clone the repository and build">
    ```bash theme={null}
    git clone https://github.com/malisper/pgrust.git
    cd pgrust

    cargo build --release --locked --bin postgres
    ```

    The compiled binary lands at `target/release/postgres`. A cold build on a modern laptop typically takes 5–10 minutes.

    <Note>
      The published downloadable binaries are built with `--profile dist`, which enables fat LTO for a faster binary at the cost of a much longer compile time. For local development, `--release` is sufficient.
    </Note>
  </Step>

  <Step title="Run the binary">
    Follow the same environment variable, `initdb`, and startup steps from the platform tabs above, substituting `target/release/postgres` as the binary path.
  </Step>
</Steps>