Examples

The examples/ directory in the repository contains five standalone applications. Each one is a complete project — real schema, real migrations, generated types, and a running HTTP server — designed to show how pg-flux fits into different stacks. Every example passes pg-flux drift and pg-flux verify cleanly and runs end-to-end in CI.

Use them as reference implementations when setting up pg-flux in your own project.

#Summary

#fastapi-todo

View on GitHub →

The canonical Python example. Demonstrates the full pg-flux Python codegen path from schema to Pydantic model to FastAPI route.

What it exercises:

• UUID primary keys (gen_random_uuid()) and the corresponding uuid.UUID Python mapping
• ENUM type → class TodoPriority(str, Enum) generated model
• Row-level security policies declared in schema and tracked by pg-flux
• pg-flux gen --lang python producing gen/models.py with BaseModel, Create, and Update helpers
• pg-flux drift --strict and pg-flux verify --strict in CI

Quick start:

cd examples/fastapi-todo
docker compose up -d db
pg-flux migrate apply
pg-flux gen --lang python --out gen/
uvicorn app.main:app --reload

#express-bookmarks

View on GitHub →

A bookmarks service that demonstrates pg-flux TypeScript codegen, full-text search via tsvector, and JSONB metadata columns.

What it exercises:

• jsonb column with a known shape declared via a pg-flux comment hint (tstype=...)
• tsvector column populated by a DB-side trigger; column type mapped to string in TS
• GIN index on tsvector and on a JSONB path for fast full-text and structured search
• pg-flux gen --lang ts --validators=zod producing tables.ts, enums.ts, and validators.ts
• Branded IDs (--branded-ids) so BookmarkId and UserId are not interchangeable at the type level
• Insert/Update helpers (UserCreate, BookmarkCreate, BookmarkUpdate) used directly in Express route handlers

Quick start:

cd examples/express-bookmarks
docker compose up -d db
pg-flux migrate apply
pg-flux gen --lang ts --out src/db --branded-ids --insert-update-helpers --validators=zod
npm run dev

#go-events

View on GitHub →

An event-management service that exercises several PG features that are more complex to diff and regenerate correctly: IDENTITY columns, materialized views, and deferrable foreign keys.

What it exercises:

• GENERATED ALWAYS AS IDENTITY primary keys; identity columns excluded from Insert helpers
• A materialized view (event_stats) with a UNIQUE index for concurrent refresh; typed as a read-only Go struct
• A deferrable INITIALLY DEFERRED foreign key; pg-flux tracks deferability in the schema model
• text[] column with a GIN index; mapped to []string in Go
• pg-flux gen --lang go --orm-tags=sqlx with db:"" struct tags
• Multiple file layout: tables.go, enums.go, views.go, types.go, functions.go

Quick start:

cd examples/go-events
docker compose up -d db
pg-flux migrate apply
pg-flux gen --lang go --out internal/db --orm-tags=sqlx
go run ./cmd/server

#go-shop

View on GitHub →

The most feature-dense Go example. Uses two PG schemas (public and catalog), a range-partitioned table, and several advanced index and constraint types that are tricky to diff correctly.

What it exercises:

• Two schemas (public, catalog) with cross-schema foreign keys; both tracked in target_schemas
• Range-partitioned orders table (PARTITION BY RANGE (created_at)) with child partitions declared in schema
• EXCLUDE USING gist constraint on a tstzrange column
• BRIN index on the partitioned table's timestamp column; INCLUDE index on a unique constraint
• Domain type (order_ref) and composite type (money_amount) both used as column types
• SECURITY DEFINER function and stored procedure; grants on schema objects declared and diffed
• pg-flux gen --lang go --functions — all function and procedure param types emitted
• --omitempty=nullable so nullable pointer fields get json:",omitempty" tags

Quick start:

cd examples/go-shop
docker compose up -d db
pg-flux migrate apply
pg-flux gen --lang go --out internal/db --orm-tags=sqlx --functions --omitempty=nullable
go run ./cmd/server

#rust-hrm

View on GitHub →

A human-resources management API that is the most comprehensive example in the repository. It covers everything in go-shop and adds range types, trigram search, window functions in materialized views, and Rust codegen.

What it exercises:

• daterange columns for employment periods; tstzrange for shift scheduling
• pg_trgm extension with a GIN trigram index on employees.name for similarity search
• A materialized view with a window function (RANK() OVER (...)) to compute org-chart rank; typed as a read-only Rust struct with all fields Option<T>
• Multiple EXCLUDE USING gist constraints; pg-flux tracks each constraint name and expression independently
• Self-referential employees table (manager_id REFERENCES employees(id)) — nullable FK column maps to Option<i64>
• pg-flux gen --lang rust --functions --out gen/ producing the full six-file module
• type_overrides: { numeric: rust_decimal::Decimal } for salary columns
• All generated structs wired to sqlx via #[derive(sqlx::FromRow)] and enums via #[derive(sqlx::Type)]

Quick start:

cd examples/rust-hrm
docker compose up -d db
pg-flux migrate apply
pg-flux gen --lang rust --functions --out gen/
cargo run

#See also

• Codegen overview →
• Python codegen →
• Rust codegen →
• Migrations →