README
¶
rig
An opinionated Postgres-first web system generator.
You write a good Postgres schema and your business logic. rig writes everything else: models,
repositories, HTTP handlers, routing, filter plumbing, live-sync endpoints, typed Go and TypeScript
clients, an authentication foundation, file uploads, and an inbox.
generated YOU WRITE THIS generated
┌──────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ repository │ ← │ service layer │ → │ API layer │
│ models │ │ business logic │ │ handlers │
│ queries │ │ validation, rules │ │ routing │
│ pgx impl │ │ orchestration │ │ filters │
└──────────────┘ └──────────────────────┘ └──────────────┘
pgx net/http
Install
go install github.com/simonjanss/rig/cmd/rig@latest
Or download a binary from the releases. In a GitHub Actions workflow:
- uses: simonjanss/rig/.github/actions/setup-rig@v0.1.0
- run: rig validate --strict
rig is twelve Go modules released together at one version, because the CLI
generates code that imports the runtime and the two have to agree. rig version
is the version to pin the libraries to:
go get github.com/simonjanss/rig/runtime@$(rig version)
Four steps
rig sync # 1. migrations → throwaway Postgres → introspect → one config file per table
# 2. edit those config files
rig validate # 3. schema conventions and configuration consistency
rig generate # 4. compile to one IR, fan out to generators
Generators
rig generators lists them. All but the two clients are scaffolded by rig init.
| Name | What it writes |
|---|---|
model-go |
the shared entity, its enums, its query types, and its inputs |
persist-go |
the repository interface and its pgx implementation |
service-go |
API types, service interfaces, and a working default implementation |
server-go |
net/http routing, request decoding, the handler registration struct, the live-sync shape endpoints with their tenant and lifecycle filters built in, and the delete propagation |
openapi |
an OpenAPI 3.1 document: every endpoint, schema and status the API answers with, optionally served by the API at <base_path>/openapi.json |
go-client |
a typed Go client: the wire types and one method per endpoint |
ts-client |
a typed TypeScript client: the wire types, one method per endpoint, and the live-sync collections |
Documentation
docs/ is the user documentation — how to build an application with rig.
| Tutorial | An API from an empty directory, in twenty minutes |
| Concepts | The three layers, what is generated, what stays yours |
| Design | Why rig works this way, and what each choice costs |
| Schema | The columns rig recognizes by name |
| rig.yaml · Tables | The two files you write |
| Authentication | Sessions, API keys, OAuth, RBAC |
| Notifications | An inbox, with the audience worked out when it is sent |
| Presence | Who is here, and which field they are editing |
| Observability | The log, the spans, and how to read a 500 |
| Clients | The generated Go and TypeScript SDKs |
examples/ holds complete applications, built and tested in CI.
Status
Early development.
Working on rig itself: run make hooks once after cloning, to install the
pre-push hook that runs the checks. AGENTS.md has the rest.
Layout
| Path | What |
|---|---|
cmd/rig |
the CLI |
pkg/ir |
the intermediate representation every generator reads |
pkg/gen |
generator interface, registry, artifact writing |
internal/compile |
the pure compile pipeline |
runtime/ |
a separate module, imported by generated code |
auth/ |
a separate module: sessions, OAuth, API keys, RBAC |
files/ |
a separate module: uploads, the blob seam, the sweeper |
notify/ |
a separate module: the notification engine and the inbox routes |
observe/ |
a separate module: OpenTelemetry, for the projects that ask for it |
migrate/ |
a separate module: apply the project's migrations from its own binary |
rigclient/ |
a separate module: the half of a generated Go client that is not generated |
rigs3/ |
a separate module: the S3 adapter for uploads, so a project on the memory backend carries no AWS SDK |
rigtest/ |
a separate module: a test harness over rig's own tables, so a project's suite does not hand-write SQL against them |
ts/ |
a pnpm workspace: the half of a generated TypeScript client that is not generated |
A generated application depends on rig/runtime (and optionally rig/auth and
rig/migrate) — never on the CLI. A program that calls one depends on
rig/rigclient; see examples/sdk for what that looks like. A
front end that calls one depends on @rig-ts/client, and on @rig-ts/electric as
well if it subscribes to a live-sync stream.
Directories
¶
| Path | Synopsis |
|---|---|
|
auth
module
|
|
|
authmodel
module
|
|
|
cmd
|
|
|
rig
command
Command rig is the command line: sync a database into table configuration, validate it, and generate from it.
|
Command rig is the command line: sync a database into table configuration, validate it, and generate from it. |
|
files
module
|
|
|
internal
|
|
|
cli
Package cli implements the rig command line.
|
Package cli implements the rig command line. |
|
compile
Package compile turns a Postgres schema and its table configuration into the frozen document every generator reads.
|
Package compile turns a Postgres schema and its table configuration into the frozen document every generator reads. |
|
diag
Package diag collects the problems rig finds and reports them together.
|
Package diag collects the problems rig finds and reports them together. |
|
dockerdb
Package dockerdb manages the throwaway Postgres rig runs migrations against.
|
Package dockerdb manages the throwaway Postgres rig runs migrations against. |
|
gen/allgen
Package allgen imports every built-in generator for its registration.
|
Package allgen imports every built-in generator for its registration. |
|
gen/gentest
Package gentest is the shared harness for testing generators.
|
Package gentest is the shared harness for testing generators. |
|
gen/genutil
Package genutil holds what more than one Go generator needs.
|
Package genutil holds what more than one Go generator needs. |
|
gen/gobuf
Package gobuf emits Go source.
|
Package gobuf emits Go source. |
|
gen/goclient
Package goclient generates a Go SDK for the API: the types a caller holds and one method per endpoint.
|
Package goclient generates a Go SDK for the API: the types a caller holds and one method per endpoint. |
|
gen/modelgo
Package modelgo generates the model layer: the entity, its enums, its query types, and the inputs that change it.
|
Package modelgo generates the model layer: the entity, its enums, its query types, and the inputs that change it. |
|
gen/openapigen
Package openapigen generates an OpenAPI 3.1 document from the compiled document, so a specification cannot describe an API that does not exist.
|
Package openapigen generates an OpenAPI 3.1 document from the compiled document, so a specification cannot describe an API that does not exist. |
|
gen/persistgo
Package persistgo generates the persistence layer: a repository interface and its pgx implementation.
|
Package persistgo generates the persistence layer: a repository interface and its pgx implementation. |
|
gen/servergo
Package servergo generates the HTTP layer: routing, decoding, and the registration struct.
|
Package servergo generates the HTTP layer: routing, decoding, and the registration struct. |
|
gen/servicego
Package servicego generates the API layer's types and the interface your service layer implements.
|
Package servicego generates the API layer's types and the interface your service layer implements. |
|
gen/tsbuf
Package tsbuf builds one TypeScript file.
|
Package tsbuf builds one TypeScript file. |
|
gen/tsclient
Package tsclient generates a TypeScript SDK for the API: the types a front end holds, one method per endpoint, and a factory per live-sync stream.
|
Package tsclient generates a TypeScript SDK for the API: the types a front end holds, one method per endpoint, and a factory per live-sync stream. |
|
godoccheck
command
Command godoccheck fails on an exported symbol with no doc comment.
|
Command godoccheck fails on an exported symbol with no doc comment. |
|
introspect
Package introspect reads a live Postgres schema into rig's intermediate representation.
|
Package introspect reads a live Postgres schema into rig's intermediate representation. |
|
migcheck
Package migcheck checks a project's migration file names before they are applied to anything.
|
Package migcheck checks a project's migration file names before they are applied to anything. |
|
naming
Package naming converts between the three casings rig deals with: the snake_case of Postgres, the PascalCase of Go and TypeScript identifiers, and the camelCase of JSON keys.
|
Package naming converts between the three casings rig deals with: the snake_case of Postgres, the PascalCase of Go and TypeScript identifiers, and the camelCase of JSON keys. |
|
pgtypes
Package pgtypes maps Postgres types onto Go types and scan strategies.
|
Package pgtypes maps Postgres types onto Go types and scan strategies. |
|
project
Package project reads rig.yaml, the file that marks the root of a rig project and configures everything that is not per-table.
|
Package project reads rig.yaml, the file that marks the root of a rig project and configures everything that is not per-table. |
|
release
command
Command release prepares a lockstep release of every published rig module.
|
Command release prepares a lockstep release of every published rig module. |
|
revision
Package revision records when a project's API surface last changed.
|
Package revision records when a project's API surface last changed. |
|
scaffold
Package scaffold writes the files a new rig project starts from.
|
Package scaffold writes the files a new rig project starts from. |
|
tableconf
Package tableconf reads the per-table YAML that annotates an introspected schema.
|
Package tableconf reads the per-table YAML that annotates an introspected schema. |
|
tablesync
Package tablesync keeps table configuration in step with the database.
|
Package tablesync keeps table configuration in step with the database. |
|
version
Package version answers what build of rig this is.
|
Package version answers what build of rig this is. |
|
yamlconf
Package yamlconf loads YAML configuration and keeps track of where every key came from.
|
Package yamlconf loads YAML configuration and keeps track of where every key came from. |
|
migrate
module
|
|
|
notify
module
|
|
|
observe
module
|
|
|
pkg
|
|
|
gen
Package gen defines what a generator is and how rig runs one.
|
Package gen defines what a generator is and how rig runs one. |
|
ir
Package ir defines the intermediate representation that rig compiles a Postgres schema and its table configuration into, and that every generator reads.
|
Package ir defines the intermediate representation that rig compiles a Postgres schema and its table configuration into, and that every generator reads. |
|
presence
module
|
|
|
rigclient
module
|
|
|
rigs3
module
|
|
|
rigtest
module
|
|
|
runtime
module
|
Click to show internal directories.
Click to hide internal directories.