From bdcead133cff4d53068e1bee0104bb5622b1092e Mon Sep 17 00:00:00 2001 From: sidgaikwad Date: Tue, 15 Sep 2026 17:29:01 +0530 Subject: [PATCH] docs: document the splinter.public_buckets contract 0025_public_bucket_allows_listing reads its bucket list from the splinter.public_buckets setting, which the splinter.sql preamble populates transaction-locally. A consumer that runs the lint query outside that transaction gets an empty bucket list and zero findings, which reads as a clean result rather than a lint that never ran. The README already documents the equivalent pgrst.db_schemas contract, so document this one alongside it, including the single-transaction requirement and the same constraint for splinter.json consumers, whose manifest exposes setup and query as separate fields. --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 023ed88..6b3d36a 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,18 @@ set pgrst.db_schemas = 'public, graphql_public, ...'; Without this, exposures in non-`public` schemas will not be reported. +### Storage lints and `splinter.public_buckets` + +`0025_public_bucket_allows_listing` does not read `storage.buckets` itself. It reads the list of public buckets from the `splinter.public_buckets` setting, which the preamble at the top of `splinter.sql` populates **transaction-locally** via `set_config(..., true)`. + +Run the lints in a single transaction so the preamble and the lint query share it: + +```bash +psql --single-transaction -f splinter.sql +``` + +When the setting is not visible, the lint reads an empty bucket list and reports **zero findings**, which is indistinguishable from a project with no affected buckets. The same applies to consumers of the `splinter.json` manifest: a lint's `query` must run in the same transaction as its `setup`. + ## Lint Interface Each lint creates a view that returns a common interface. The interface is: