README
¶
pdbcore
Shared engine for pdbq (GraphQL) and
pdbr (REST): everything about turning a
live PostgreSQL database into an API that is not specific to one transport.
Library only — no binary, no GraphQL or REST grammar, no gqlparser
(CI asserts go list -deps ./... contains no GraphQL dependency).
The products own the transport: schema/route generation, request parsing, SQL compilation, response shaping. pdbcore owns what both need identically: the catalog model and its introspection, naming helpers, the schema cache and watcher, PostGIS value handling, authentication, transaction execution with RLS identity, JWT minting, HTTP scaffolding, configuration loading, the generic plugin registry, the catalog half of smart comments, and the one test fixture both products are tested against.
Packages
| Package | What it holds |
|---|---|
introspect |
Catalog model (Table, Column, Constraint, ForeignKey, Index, Enum, Composite, Function, privileges, RLS flag, comments), Introspect(ctx, querier, schemas) (pg_catalog reader incl. @enum table conversion), Diff (human-readable drift lines), Hash, CatalogFormatVersion |
smarttags |
PostGraphile-style smart-comment parser: Parse, Strip, Tags, Omits, @behavior, list splitting |
inflect |
naming pipeline types (Kind, Input, Next) + string helpers (UpperCamel, LowerCamel, Singularize, Pluralize, EnumValue, ByColumns); products define their own Kind constants and Default |
cache |
gzip+JSON catalog cache: Save / Load / Check, format-version and content-hash checks, 256 MiB decompression guard |
watch |
Watcher: DDL event trigger + LISTEN/NOTIFY (TriggerName, Channel), hash-polling fallback when the trigger cannot be installed → OnChange(*Catalog) |
postgis |
spatial value layer: flavour detection, GeoJSON/WKT/EWKT parsing to one bound parameter, filter Ops, derived accessors, transform/simplify/KNN/distance SQL |
auth |
Authenticator: JWT (HS*, JWKS RS*/ES* with kid-matched cache), trusted-gateway claim headers with TrustedProxies, role resolution and allowlist; ErrInvalidToken / ErrRoleNotAllowed |
pgexec |
pool Connect, RunTx (isolation, SET LOCAL ROLE, claims via set_config(prefix.k, v, true), 40001/40P01 retries), Identity, Classify PG errors into classes with dev/prod/strict message policies, QuoteIdent/ValidRole/ValidClaimKey |
jwtmint |
composite-typed function results → signed HS256 JWT (MintsFunction, Mint, Sign) |
httpx |
CORS + preflight, gzip, Healthz, ListenAndServe with the standard timeouts and graceful shutdown |
confx |
koanf Load (defaults < YAML < env < changed flags), env key mapper (_ → ., __ → _, comma-separated lists), ExampleYAML from koanf/doc tags, Discover, ParseTrustedProxy, shared config sections (Database, Schema, Filters, RLS/Auth, TX, Watch, Errors, Plugins, Log) + Validate* helpers, AuthConfig(RLS) |
plugin |
Plugin, Registry (priority + registration order), CatalogHook, InflectionHook, TransformCatalog, Inflector chain |
smartcomments/catalog |
catalog half of the smart-comments plugin (@omit, @primaryKey, @unique, @foreignKey, @notNull, @filterable, @name index) — products add their transport half on top |
testutil |
FixtureSQL (embedded DDL) and FixtureCatalog(), the one fixture both products test against; testutil/cmd/fixture prints the SQL; drift_test.go is the fixture drift gate |
Every package has a package comment describing its contract; go doc github.com/suprbdev/pdbcore/<pkg> is the reference.
How products consume it
import (
"github.com/suprbdev/pdbcore/cache"
"github.com/suprbdev/pdbcore/introspect"
"github.com/suprbdev/pdbcore/pgexec"
)
cat, _ := introspect.Introspect(ctx, pool, cfg.Schema.Schemas) // or cache.Load(path)
// ... the product builds its schema / routes from cat and runs its own compiler ...
err := pgexec.RunTx(ctx, pool,
pgexec.TxOptions{Isolation: iso, MaxRetries: 2, RLS: true},
pgexec.Identity{Role: role, Claims: claims, ClaimsPrefix: "pdbq.claims"},
func(q pgexec.Querier) error { return q.QueryRow(ctx, sql, args...).Scan(&data) })
Both products embed the confx sections in their own Config struct (the
product owns Server and its defaults such as watch.channel and the claim
header prefix), wrap plugin.Registry with their transport-specific hooks,
and register smartcomments/catalog.New() inside their smart-comments
plugin. rls.claims_prefix defaults to pdbq.claims in both so RLS policies
work unchanged behind either server; watch.TriggerName differs
(pdbq_watch / pdbr_watch) so both can watch one database.
Until the first tag lands the products point at a sibling checkout:
// go.mod (pdbq, pdbr)
replace github.com/suprbdev/pdbcore => ../pdbcore
The fixture and the drift gate
testutil.FixtureSQL (testutil/fixture.sql) and testutil.FixtureCatalog()
(testutil/catalog.go) describe the same schema: users/posts/comments with
RLS policies on posts, places/events (PostGIS), a metrics view,
enums, a composite jwt type, and the functions the products' RPC /
computed-column tests use. They must stay in sync:
testutil/drift_test.go (TestFixtureCatalogMatchesLiveIntrospection) loads
FixtureSQL into a database, introspects it and asserts the result equals
FixtureCatalog() (needs PDBCORE_TEST_DATABASE_URL; make test-e2e
provides one). Products regenerate db/init/01-schema.sql from it (their
make fixture runs go run github.com/suprbdev/pdbcore/testutil/cmd/fixture)
and run their goldens against FixtureCatalog(), so a fixture change is a
pdbcore change first and a golden update in both products second.
Versioning
Semver v0.x.y while pre-1.0: minor bumps may break API, patch bumps may
not; products pin an exact version. introspect.CatalogFormatVersion is
owned here — bumping it is a minor release and both products upgrade in
lockstep so a cache written by one (pdbq schema dump / pdbr schema dump)
loads in the other. Fixture changes are patch/minor releases; products
regenerate their goldens on upgrade.
Development
make test # hermetic unit tests (go test -race ./...)
make test-e2e # DB-backed tests (fixture drift gate, pgexec RLS matrix, watch) on a disposable PostGIS (project pdbcore-test, host port 5434)
make lint # golangci-lint (falls back to go vet)
make fixture # print testutil.FixtureSQL
make release # interactive: clean tree check, version prompt, test+lint, annotated tag, push
CI (.github/workflows/ci.yaml) runs vet, golangci-lint, the race tests and
the no-GraphQL-dependency check, plus the DB-backed suites against a PostGIS
service.
Release flow
pdbcore is a library, so a release is a tag: make release verifies the tree
is clean, prompts for vX.Y.Z, runs make test lint, tags and pushes; the
Release workflow (.github/workflows/release.yaml) re-runs the race tests
and creates the GitHub release with generated notes (no binaries; publishing
is skipped under act).
Consumers then bump with go get github.com/suprbdev/pdbcore@vX.Y.Z (and,
for the very first tag, delete their replace ../pdbcore line and any
"check out pdbcore next to the repo" / go mod vendor steps in their
Makefile, Dockerfile and workflows). Order for the first release: pdbcore
v0.1.0 → pdbq v0.11.0 → pdbr v0.1.0; the exact steps are in pdbr's
docs/deployment.md § Releasing.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth turns an HTTP request into verified claims and a database role: a JWT (HS* via shared secret, RS*/ES* via a cached JWKS endpoint), trusted-gateway claim headers, or nothing.
|
Package auth turns an HTTP request into verified claims and a database role: a JWT (HS* via shared secret, RS*/ES* via a cached JWKS endpoint), trusted-gateway claim headers, or nothing. |
|
Package cache (de)serializes the introspected Catalog so a product can boot without touching pg_catalog: gzip-compressed JSON with a format version and a content hash for drift detection (`schema dump|check`).
|
Package cache (de)serializes the introspected Catalog so a product can boot without touching pg_catalog: gzip-compressed JSON with a format version and a content hash for drift detection (`schema dump|check`). |
|
Package confx is the configuration toolkit shared by the products: koanf loading with the YAML < env < changed-flags precedence, the env key mapper, reference-YAML generation from `koanf`+`doc` struct tags, and the config sections (with validation) that both products expose verbatim.
|
Package confx is the configuration toolkit shared by the products: koanf loading with the YAML < env < changed-flags precedence, the env key mapper, reference-YAML generation from `koanf`+`doc` struct tags, and the config sections (with validation) that both products expose verbatim. |
|
Package httpx holds the transport-neutral HTTP scaffolding shared by the products: CORS, gzip, the health handler, and ListenAndServe with the standard timeouts and graceful shutdown.
|
Package httpx holds the transport-neutral HTTP scaffolding shared by the products: CORS, gzip, the health handler, and ListenAndServe with the standard timeouts and graceful shutdown. |
|
Package inflect defines the naming pipeline shared by every product: an open Kind, the Input a naming hook receives, the Next continuation, and the pure string helpers (camel casing, singular/plural, enum value names).
|
Package inflect defines the naming pipeline shared by every product: an open Kind, the Input a naming hook receives, the Next continuation, and the pure string helpers (camel casing, singular/plural, enum value names). |
|
Package introspect reads pg_catalog and produces a Catalog — the single serializable model that drives API building, caching, and plugins.
|
Package introspect reads pg_catalog and produces a Catalog — the single serializable model that drives API building, caching, and plugins. |
|
Package jwtmint turns function results of one composite type into signed JWTs (PostGraphile's pgJwtType): a function returning schema.type yields an HS256 token string whose claims are the composite's fields; an exp field becomes the token expiry.
|
Package jwtmint turns function results of one composite type into signed JWTs (PostGraphile's pgJwtType): a function returning schema.type yields an HS256 token string whose claims are the composite's fields; an exp field becomes the token expiry. |
|
Package pgexec is the transport-neutral execution layer shared by pdbq and pdbr: pool setup, per-request transactions with RLS role switching and claims via set_config (SET LOCAL only, so pooled connections never leak identity), serialization-failure retries, identifier quoting, and PostgreSQL error classification with the dev/prod/strict message policy.
|
Package pgexec is the transport-neutral execution layer shared by pdbq and pdbr: pool setup, per-request transactions with RLS role switching and claims via set_config (SET LOCAL only, so pooled connections never leak identity), serialization-failure retries, identifier quoting, and PostgreSQL error classification with the dev/prod/strict message policy. |
|
Package plugin defines the transport-neutral hook surfaces and the ordered registry.
|
Package plugin defines the transport-neutral hook surfaces and the ordered registry. |
|
Package postgis models the PostGIS spatial types as a small, catalog-driven value layer shared by the schema builder, the SQL compiler, and the postgis plugin.
|
Package postgis models the PostGIS spatial types as a small, catalog-driven value layer shared by the schema builder, the SQL compiler, and the postgis plugin. |
|
smartcomments
|
|
|
catalog
Package catalog is the catalog half of the smart-comments plugin: it indexes PostGraphile-style tags parsed from database COMMENTs and applies the ones with a structural representation in the introspect.Catalog — @omit on whole objects, @omit create/update/delete → privilege flags, @primaryKey / @unique / @foreignKey synthesis, @notNull / @nullable, and @filterable / @sortable as a synthetic index.
|
Package catalog is the catalog half of the smart-comments plugin: it indexes PostGraphile-style tags parsed from database COMMENTs and applies the ones with a structural representation in the introspect.Catalog — @omit on whole objects, @omit create/update/delete → privilege flags, @primaryKey / @unique / @foreignKey synthesis, @notNull / @nullable, and @filterable / @sortable as a synthetic index. |
|
Package smarttags parses PostGraphile-style "smart comments": lines at the start of a database COMMENT beginning with '@' are machine-readable tags, everything after the first non-tag line is the human description.
|
Package smarttags parses PostGraphile-style "smart comments": lines at the start of a database COMMENT beginning with '@' are machine-readable tags, everything after the first non-tag line is the human description. |
|
Package testutil provides the shared test fixture: FixtureSQL (the DDL both products' compose stacks and e2e suites load) and FixtureCatalog, a hand-built Catalog mirroring what introspecting that DDL yields, so builder and compiler tests run without a database.
|
Package testutil provides the shared test fixture: FixtureSQL (the DDL both products' compose stacks and e2e suites load) and FixtureCatalog, a hand-built Catalog mirroring what introspecting that DDL yields, so builder and compiler tests run without a database. |
|
cmd/fixture
command
Command fixture prints testutil.FixtureSQL so product repos can generate their compose init script from the module:
|
Command fixture prints testutil.FixtureSQL so product repos can generate their compose init script from the module: |
|
Package watch re-introspects on DDL changes (dev mode).
|
Package watch re-introspects on DDL changes (dev mode). |