pgrust Documentation

Pages

1. OverviewWhat 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.
2. InstallationPrerequisites, system packages, build-time share-dir wiring, and producing the release postgres binary from a clone.
3. QuickstartShortest local path: build, --initdb with -L, start with required stack and io_method settings, connect with psql, and verify version() and a trivial query.
4. DockerRun malisper/pgrust or a local image build with the official postgres-shaped contract, connect with psql, and confirm first-boot init via entrypoint.
5. Compatibility and statusPostgres 18.3 behavior and on-disk compatibility, regression-oracle model, non-production status, and extension/PL boundaries that block generic Postgres extensions.
6. Process modes and dispatchHow the single postgres binary dispatches: postmaster default, --single, --boot, --check, --describe-config, and the pgrust-specific initdb/--initdb entry.
7. Install paths and share directoryPGRUST_PGSHAREDIR and related build-time path env vars, runtime -L override, vendored share tree contents, and why wrong share/tz paths break boot.
8. Seams and builtin librariesSeam registration model, seams-init aggregation, and dfmgr builtin-library registration that replaces dlopen for ported contrib and regress helpers.
9. Initialize a clusterCreate PGDATA with postgres --initdb: supported flags, directory layout, bootstrap and post-bootstrap phases, and success signal text.
10. Run the serverStart postmaster with -D, socket/TCP flags, mandatory io_method=sync and stack settings, connect with psql, and confirm readiness.
11. Boot from existing Postgres dataConstraints for reusing a Postgres 18.3 PGDATA: control file checks, major-version expectations, and practical recovery when byte order or catalog state does not match.
12. Use contrib extensionsPorted contrib modules registered as builtins (citext, hstore, ltree, pg_trgm, pgcrypto, pg_stat_statements, uuid-ossp, and others), CREATE EXTENSION against vendored control/SQL, and what remains unported.
13. Run regression testsClone-only scripts/run-regression against vendored PG 18.3 SQL/expected files, psql client requirements, selective test names, and optional isolation/auth/recovery TAP harnesses.
14. postgres CLI referenceFlags from --help, must-be-first dispatch options, -c/--NAME=VALUE GUC overrides, and exit paths for --version and --describe-config.
15. initdb options referenceSupported pgrust initdb argv: -D/--pgdata, -U/--username, -L, -E/--encoding, locale flags, --wal-segsize; space-separated parsing; unsupported options that error.
16. Configuration referenceRequired and high-impact runtime settings: io_method default vs sync, max_stack_depth, RUST_MIN_STACK, ulimit -s, listen_addresses, and build-time PGRUST_* path env vars.
17. Docker environment referencePOSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB, POSTGRES_INITDB_ARGS, POSTGRES_HOST_AUTH_METHOD, PGDATA, init scripts under /docker-entrypoint-initdb.d, and injected server opts.
18. Test harness environment referenceEnvironment variables and defaults for run-regression, serial/pg_regress, isolation, auth/ldap TAP, and recovery TAP: PGRUST_BIN, PGRUST_PSQL, PG_SRC, PG_INSTALL, ports, OUTDIR.
19. Build from sourceHost packages, PGRUST_PGSHAREDIR bake-in, cargo build --release --locked --bin postgres, wasm64 single-user notes, and binary location target/release/postgres.
20. Workspace and crate checksCargo workspace scale, fast-check profile, scripts/check-crate and scripts/gate-crate, and how to validate a single ported crate plus seams-init.
21. TroubleshootingKnown failure modes: missing io_method=sync, stack overflows, wrong share/tz path, initdb option gaps, root execution refused, missing psql client, and unported extension loads.