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
sqlb survey $SRC $SCRATCH               report what sqlb could describe of a
                                        database it did not declare

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.

The one verb that does not ¶

`survey` is the exception, and for the reason that proves the rule: it builds its registry by introspecting a live database rather than by importing a declaration, so there is nothing to link in and nothing to compile. It takes two DSNs and runs in this process. See survey.go.

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.