1# Chapter 1: crates, four crates and one wall
2
3A Postgres extension lives inside the database server's own process. It is
4handed raw pointers into the server's memory, it is called back from C, and
5when Postgres raises an error it does not return: it `longjmp`s straight past
6whatever was running. Rust can do all of that, but only inside `unsafe`
7blocks, which are the places where the compiler stops checking and trusts
8you instead.
9
10The whole design of this folder is to keep those places in one crate. A
11*crate* is Rust's unit of compilation (think of an npm package), and every
12crate here except one starts with `#![forbid(unsafe_code)]`, a line that
13makes the compiler refuse any `unsafe` at all. The one exception,
14`postjevsql-pg`, wraps every C surface the extension needs in safe types, and
15everything else is built on those.
16
17```mermaid
18flowchart BT
19  protocol["jev-protocol (jevcrates): questions, request bytes, answers"]
20  client["jev-client (jevcrates): retries, timeouts, redials"]
21  core["postjevsql-core: decisions, no I/O"]
22  pg["postjevsql-pg: the only unsafe"]
23  ext["postjevsql: the extension"]
24  sidecar["postjevsql-sidecar: sidecar setup"]
25  client --> protocol
26  core --> protocol
27  pg --> client
28  pg --> core
29  ext --> pg
30  ext --> core
31  ext --> client
32  ext --> protocol
33```
34
35(An arrow means "uses". The two at the bottom come from jevcrates, the Jev
36client shared with the owner's other Jev projects, in chapter 28.
37`postjevsql-sidecar` stands alone: it sets a sidecar up and never asks Jev
38anything.)
39
40> **Aside.** "Forbid" is stronger than it sounds. `#![deny(unsafe_code)]`
41> could be overridden further down with an `allow`; `forbid` cannot. And it
42> holds even through pgrx's macros, which generate `unsafe` code of their own
43> inside the extension crate: the source spans pgrx gives that code do not
44> trip the lint. No published project was found relying on that, so a
45> proc-macro experiment checked it, and the contract records the result.
46
47> **Try it.** `cargo test -p postjevsql-core` runs the pure crate's tests on
48> any machine with Rust, no Postgres needed. Then
49> `grep -rl --include='*.rs' 'forbid(unsafe_code)' crates` lists the crate
50> roots that hold the wall, and nothing in `postjevsql-pg` is among them.
51
52The chapters that follow take the crates in the order a query meets them:
53the SQL functions you call (2–4), the scan and the runtime that run them
54(5–7), the pure decisions they lean on (8–9), and the sidecar, for databases
55you cannot install into (10–12).
56
57## For the people who maintain it
58
59| Crate | What |
60| --- | --- |
61| [postjevsql/](postjevsql/) | The pgrx extension: the settings, the SQL functions, the cache table, and the judge that answers every call. Builds `:ext`, the installable tree. |
62| [postjevsql-pg/](postjevsql-pg/) | The only crate allowed `unsafe`: the WaitEventSet executor, the HTTP/2 client, DNS, the shared rate limiter, and the batch scan. |
63| [postjevsql-core/](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. |
64| [postjevsql-sidecar/](postjevsql-sidecar/) | Sidecar setup: the config, the secrets, the sync plan, and the CLI that applies them. |
65
66Each crate is declared in its `BUCK` file through `build/defs.bzl`'s
67`first_party_*` macros, which also give it a lint test. The `Cargo.toml`
68beside each is generated from those (chapter 20).
69
70← Previous: [Prologue](../) · Up: [postjevsql](../) · Next: [Chapter 2, postjevsql/](postjevsql/) →