sqlb

Overview ¶

Command sqlb keeps a project's generated code and migration history in step with its schema declaration, and reports when either has drifted from it.

sqlb generate ./taskschema              write every artefact the project declares
sqlb check ./taskschema                 report stale artefacts, write nothing
sqlb migrate -name adds_priority ./taskschema   write the next migration
sqlb migrate -check ./taskschema        report whether the schema has moved ahead

Two gates, and only one of them needs a database ¶

`check` compares committed output with what the emitters produce now, which is a pure function of the schema. `migrate -check` asks whether the committed migration history *builds* that schema, and the only trustworthy way to answer it is to replay the history into an empty Postgres — reading a live database reports what it looks like, not whether the migrations produce it (ADR-0014). So the first runs on every push and the second needs a scratch database, and they are separate for that reason.

Why this needs a package argument ¶

The schema is Go, and a table is registered by the side effect of importing the package that declares it (ADR-0004). A prebuilt binary therefore cannot read a registry — nothing is in it until the schema package is linked in. So this command does the only thing that can work: it writes a driver program that imports the named package, compiles it inside your module, runs it, and deletes it. The argument is the package to import, in the same form `go build` takes.

What the driver does once it is running lives in codegen.Main, not in emitted source, so that the interesting half of this command is ordinary tested code.

What it costs ¶

A `go run`, which on a warm build cache is well under a second and on a cold one is a compile of your module's dependency graph. That is the price of the schema being Go rather than a config file, and it is paid here instead of in the per-project `cmd/gen/main.go` this replaces.