# Overview
> What pgrust exposes as a Postgres 18.3-shaped server binary, who should use it, status limits, and the first docs routes for Docker, source build, and regression verification.
- Repository: malisper/pgrust
- GitHub: https://github.com/malisper/pgrust
- Human docs: https://grok-wiki.com/public/docs/malisper-pgrust-7e0c8e82bc21
- Complete Markdown: https://grok-wiki.com/public/docs/malisper-pgrust-7e0c8e82bc21/llms-full.txt
## Source Files
- `README.md`
- `Cargo.toml`
- `LICENSE`
- `crates/_support/seam/init/src/bin/postgres.rs`
- `crates/backend/main/main_main/src/lib.rs`
- `docker/README.md`
---
---
title: "Overview"
description: "What pgrust exposes as a Postgres 18.3-shaped server binary, who should use it, status limits, and the first docs routes for Docker, source build, and regression verification."
---
pgrust ships a single release binary named `postgres` that presents a PostgreSQL **18.3**-shaped server: the same wire protocol and client contract as stock Postgres, on-disk compatibility with a Postgres 18.3 data directory, and the version banner `postgres (PostgreSQL) 18.3`. The process entry is `crates/_support/seam/init/src/bin/postgres.rs`, which installs seams via `init::init_all()`, then calls `main_main::pg_main` (port of `src/backend/main/main.c`). Catalog bootstrap uses a built-in `initdb` / `--initdb` driver on the same binary rather than a separate C `initdb`. The project is licensed **AGPL-3.0**.
## What you get
| Surface | Behavior |
| --- | --- |
| Binary | `target/release/postgres` from `cargo build --release --locked --bin postgres` (crate `seams-init`) |
| Default mode | Postmaster (no special first argv flag) |
| Cluster create | `postgres --initdb` or `postgres initdb` (pgrust-specific; not a C DispatchOption) |
| Version | `--version` / `-V` → `postgres (PostgreSQL) 18.3` |
| Share data | Vendored tree `vendor/postgres-18.3/share` (or image `/usr/share/postgresql/18`); bake with `PGRUST_PGSHAREDIR`, override at init with `-L` |
| Clients | Any Postgres 18-compatible client (`psql`); the server does not replace `psql` |
| Docker | Official-postgres-shaped image contract (`POSTGRES_*`, `PGDATA`, `/docker-entrypoint-initdb.d`, port 5432) |
```text
clients (psql / libpq)
|
v
target/release/postgres (single binary)
|-- --initdb | initdb --> initdb driver (re-exec --boot / --single)
|-- --single --> standalone backend
|-- --boot | --check --> bootstrap mode
|-- --describe-config --> GUC dump + exit
+-- (default) --> postmaster_main
|
+-- PGDATA + vendor share (postgres.bki, extension/, timezone/, …)
```
## Who should use it
- **Experimenters and contributors** who want a Postgres-behavior-compatible Rust server they can change from the inside.
- **Compatibility explorers** validating queries against the vendored Postgres 18.3 regression oracle (`scripts/run-regression`, 46k+ queries at launch verification).
- **Docker users** who need a postgres-image-shaped container backed by the Rust binary (`malisper/pgrust` or a local `Dockerfile` build).
- **Not** production operators: the project states it is not production-ready and not performance-optimized.
## Status and limits
pgrust is **not production-ready**. It is **not performance optimized**. Treat it as a research and compatibility surface, not a drop-in production replacement.
| Area | Current boundary |
| --- | --- |
| Behavior oracle | Matches Postgres expected output across more than 46,000 regression queries (launch verification) |
| On-disk | Can boot from an existing Postgres **18.3** data directory (same major / catalog generation assumptions as stock 18.3) |
| I/O | Runtime must use `-c io_method=sync` — sync is the only I/O method this port supports |
| Stack | Raise OS stack (`ulimit -s`) and Rust stack (`RUST_MIN_STACK`); set `-c max_stack_depth=…` (README example: 60000) |
| Extensions | Generic Postgres extensions and procedural languages (PL/Python, PL/Perl, PL/Tcl) are **not** generally compatible |
| Ported contrib | Selected modules registered as **builtins** (no `dlopen`): e.g. `citext`, `hstore`, `ltree`, `pg_trgm`, `pgcrypto`, `pg_stat_statements`, `uuid-ossp`, plus regress helpers |
| Root | Server and initdb refuse root (`check_root`); real and effective UIDs must match |
| Client tools | Regression and Docker healthchecks need a real Postgres 18 `psql`; pgrust does not ship a `psql` replacement |
| wasm | Binary builds for `wasm64` single-user paths; initdb re-exec is native-only |
## Process dispatch (binary argv)
Must-be-first long options (after `--`) map like C `main.c`, plus the pgrust initdb intercept:
| First argument | Outcome |
| --- | --- |
| *(none / ordinary flags)* | `DISPATCH_POSTMASTER` → `postmaster_main` |
| `--single` | Standalone backend |
| `--boot` | Bootstrap mode |
| `--check` | Bootstrap check-only |
| `--describe-config` | Print GUC info and exit (root check skipped) |
| `initdb` or `--initdb` | `MainOutcome::Initdb` → `initdb::initdb_main` (re-execs for `--boot` / `--single`) |
| `--help` / `-?`, `--version` / `-V` | Print and exit 0 before root check |
## First paths
### Docker
Pinned launch image: `malisper/pgrust:v0.1` (`latest` may track the same tag). Local image: `docker build -t pgrust .`.
```bash
docker run -d --name pgrust \
-e POSTGRES_PASSWORD=secret \
-p 5432:5432 \
malisper/pgrust:v0.1
# wait until ready, then:
docker exec -it -e PGPASSWORD=secret pgrust \
psql -h 127.0.0.1 -U postgres \
-c "select version(), 1 + 1 as two"
```
The image uses pgrust for both the server and `--initdb` bootstrap; only `psql` remains a C/PGDG client. The entrypoint injects `io_method=sync`, `max_stack_depth`, and a larger stack ulimit without changing the usual `postgres …` CMD contract.
### Build and run from source
Prerequisites (host packages differ by OS; see Installation). Bake the share directory into the binary, then build:
```bash
PGRUST_PGSHAREDIR="$PWD/vendor/postgres-18.3/share" \
cargo build --release --locked --bin postgres
```
Initialize and start (minimal shape from the repository README):
```bash
target/release/postgres --initdb \
-D /tmp/pgrust-data \
-L "$PWD/vendor/postgres-18.3/share" \
--no-locale \
--encoding UTF8 \
-U postgres
ulimit -s 65520
RUST_MIN_STACK=33554432 target/release/postgres \
-D /tmp/pgrust-data \
-F \
-c listen_addresses= \
-k /tmp \
-p 5432 \
-c io_method=sync \
-c max_stack_depth=60000
psql -h /tmp -p 5432 -U postgres -d postgres \
-c "select version(), 1 + 1 as two"
```
Verification signal: `version()` reports PostgreSQL 18.3 and `1 + 1` returns `2`. If the server fails immediately with I/O or stack issues, confirm `io_method=sync` and the stack GUCs/env are set.
### Regression verification (clone-only)
```bash
PGRUST_BIN="$PWD/target/release/postgres" \
scripts/run-regression
```
| Input | Role |
| --- | --- |
| `PGRUST_BIN` | pgrust server (default `target/release/postgres`) |
| `PGRUST_PSQL` | optional path to Postgres 18 `psql` if not on `PATH` |
| `vendor/postgres-18.3/` | share + `regress/sql`, `regress/expected`, `parallel_schedule` |
| Optional args | Selective test names; `test_setup` auto-prepended when missing |
No external PostgreSQL **source tree** or C `initdb` is required. Missing vendored files or a non-executable binary causes an immediate script exit with a short diagnostic.
## Repository layout (operators)
:::files
pgrust/
├── crates/_support/seam/init/ # postgres binary + init_all seam aggregation
├── crates/backend/main/main_main/ # pg_main dispatch (main.c port)
├── crates/contrib/ # ported contrib as builtins
├── vendor/postgres-18.3/ # share + regress + isolation fixtures
├── scripts/run-regression # clone-only regression driver
├── docker/entrypoint.sh # official-postgres-shaped entrypoint
└── Dockerfile # multi-stage: rustbuild + pgtools + runtime
:::
## Next
Run `malisper/pgrust` or a local image with the official postgres-shaped env contract and first-boot init.
Shortest local path: build, `--initdb` with `-L`, start with stack and `io_method=sync`, connect with `psql`.
Host packages, `PGRUST_PGSHAREDIR` bake-in, and `cargo build --release --locked --bin postgres`.
Postgres 18.3 behavior and on-disk limits, regression oracle, and extension/PL boundaries.
`scripts/run-regression` against vendored SQL/expected files and optional TAP harnesses.
Common failures: missing `io_method=sync`, stack overflows, wrong share path, root refuse, missing `psql`.