Chapter 1: crates, four crates and one wall

A Postgres extension lives inside the database server's own process. It is handed raw pointers into the server's memory, it is called back from C, and when Postgres raises an error it does not return: it longjmps straight past whatever was running. Rust can do all of that, but only inside unsafe blocks, which are the places where the compiler stops checking and trusts you instead.

The whole design of this folder is to keep those places in one crate. A crate is Rust's unit of compilation (think of an npm package), and every crate here except one starts with #![forbid(unsafe_code)], a line that makes the compiler refuse any unsafe at all. The one exception, postjevsql-pg, wraps every C surface the extension needs in safe types, and everything else is built on those.

flowchart BT
  protocol["jev-protocol (jevcrates): questions, request bytes, answers"]
  client["jev-client (jevcrates): retries, timeouts, redials"]
  core["postjevsql-core: decisions, no I/O"]
  pg["postjevsql-pg: the only unsafe"]
  ext["postjevsql: the extension"]
  sidecar["postjevsql-sidecar: sidecar setup"]
  client --> protocol
  core --> protocol
  pg --> client
  pg --> core
  ext --> pg
  ext --> core
  ext --> client
  ext --> protocol

(An arrow means "uses". The two at the bottom come from jevcrates, the Jev client shared with the owner's other Jev projects, in chapter 28. postjevsql-sidecar stands alone: it sets a sidecar up and never asks Jev anything.)

Aside. "Forbid" is stronger than it sounds. #![deny(unsafe_code)] could be overridden further down with an allow; forbid cannot. And it holds even through pgrx's macros, which generate unsafe code of their own inside the extension crate: the source spans pgrx gives that code do not trip the lint. No published project was found relying on that, so a proc-macro experiment checked it, and the contract records the result.

Try it. cargo test -p postjevsql-core runs the pure crate's tests on any machine with Rust, no Postgres needed. Then grep -rl --include='*.rs' 'forbid(unsafe_code)' crates lists the crate roots that hold the wall, and nothing in postjevsql-pg is among them.

The chapters that follow take the crates in the order a query meets them: the SQL functions you call (2–4), the scan and the runtime that run them (5–7), the pure decisions they lean on (8–9), and the sidecar, for databases you cannot install into (10–12).

For the people who maintain it

Crate	What
postjevsql/	The pgrx extension: the settings, the SQL functions, the cache table, and the judge that answers every call. Builds `:ext`, the installable tree.
postjevsql-pg/	The only crate allowed `unsafe`: the WaitEventSet executor, the HTTP/2 client, DNS, the shared rate limiter, and the batch scan.
postjevsql-core/	The logic with no Postgres and no I/O: the batch planner, the cache key, the GCRA limiter, the learned token ratio, the label-tree and chunk-and-shortlist searches.
postjevsql-sidecar/	Sidecar setup: the config, the secrets, the sync plan, and the CLI that applies them.

Each crate is declared in its BUCK file through build/defs.bzl's first_party_* macros, which also give it a lint test. The Cargo.toml beside each is generated from those (chapter 20).

← Previous: Prologue · Up: postjevsql · Next: Chapter 2, postjevsql/ →