Chapter 17: tools, the helpers that write files so nobody has to

Four small Rust programs, none of which ships to anyone who installs the extension. Each exists because a file in this repository would otherwise have to be kept by hand, and anything kept by hand eventually lies.

flowchart LR
  so["the built postjevsql.so"] --> PS["pgrx-schema"] --> sql["postjevsql--0.0.1.sql"]
  bk["the BUCK files"] --> CG["cargo-gen"] --> cargo["every Cargo.toml"]
  ar["the crate archives buck fetched"] --> TN["third-party-notices"] --> tp["THIRD-PARTY, THIRD-PARTY-sidecar"]
  gs["the release gates"] --> RG["record-gates"] --> fx["tests/fixtures/*.json"]

Two of them follow one pattern, worth knowing once. The tool generates the file inside the buck build, a drift test compares that with the copy committed in the repository and fails when they differ, and buck2 run //tools/<tool>:update writes the generated copy back into the checkout. So the committed file can be stale for exactly as long as it takes the next test run to notice. The other two differ on purpose: pgrx-schema's output is never committed, only built, and record-gates writes its fixtures once and refuses to overwrite them unless told to (--rerecord).

Aside. Why commit generated files at all? Because they are for people who do not run buck. The Cargo workspace lets anyone cargo build or cargo pgrx install from a plain clone, and the licence notices are there for anyone reading the code, as well as installed beside the binaries. Generating them keeps them true; committing them makes them useful.

Try it. nix develop -c buck2 test //tools/... runs both drift tests and the tools' lint tests. Change a dependency in a BUCK file without running the update, and //tools/cargo-gen:drift tells you which manifest is now stale.

For the people who maintain it

← Previous: Chapter 16, nix/ · Up: postjevsql · Next: Chapter 18, pgrx-schema/ →