schema

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package schema is the declarative schema DSL for sqlb.

A schema is written as ordinary Go values, which makes it the single source of truth for migrations, models, REST handlers and the OpenAPI document: 

var User = schema.Table("users",
    schema.UUIDv7("id").PrimaryKey(),
    schema.Text("email").Unique().Searchable(),
    schema.Int("age").Nullable().Filterable(),
    schema.Ref("org", Org).OnDelete(schema.Cascade),
    schema.Timestamps(),
).Expose(schema.REST{Path: "/users", Ops: schema.CRUD | schema.List})

Capabilities such as Filterable and Sortable are opt-in per column. A column that does not declare a capability can never be reached through it from the REST layer, which is what separates sqlb from exposing the database directly.

Index

Examples

Constants

View Source 
const CRUD = OpCreate | OpRead | OpUpdate | OpDelete

CRUD is the conventional single-row operation set. Combine it with OpList for a fully exposed collection.

View Source 
const DefaultExpandLimit = 50

DefaultExpandLimit is the cap an expanded collection takes when it declares none. It mirrors the engine's own default, and sqlb's model test asserts the two agree — a schema package that disagreed with the runtime would publish a number the responses do not honour.

View Source 
const ManifestVersion = "1"

ManifestVersion is bumped when the manifest shape changes incompatibly.

Variables

This section is empty.

Functions

func CheckIdent 

func CheckIdent(name string) error

CheckIdent reports why the DSL cannot declare a table or column called name, or nil when it can.

It is exported for introspection, which reads names a database already has rather than names an author chose. Those two are not the same set — a camelCase column is legal in Postgres and undeclarable here — and an importer needs to say which construct it had to skip, not fail the whole import with a message about what the DSL considers impossible.

func IsArrayElement 

func IsArrayElement(t Type) bool

IsArrayElement reports whether t may be the element type of an array column.

jsonb and bytea are excluded: both already hold a composite value, and an array of either is a shape no generated client can narrow past `unknown`.

func Register 

func Register(t *TableDef)

Register adds a table to the default registry. Table calls this for you.

func Validate 

func Validate() error

Validate checks the default registry.

func WriteManifest 

func WriteManifest(path string) error

WriteManifest writes the default registry's manifest to path, creating parent directories as needed.

Types

type Action 

type Action struct {
	// Name is the verb. It appears in the URL, in the operation ID, and in the
	// generated identifiers — "complete" gives POST /tasks/{id}/complete and an
	// Actions.CompleteTask field.
	Name string

	// Path is the sub-path under the collection. It defaults to
	// "/{id}/"+Name, which is the item form.
	//
	// A path that does not contain "{id}" is a *collection* action: there is no
	// row to fetch, so the verb receives only the body and answers 204. Note
	// what that costs — with no generated fetch there is no BeforeQuery for a
	// declared scope to hang off, so a collection action inherits none of
	// ADR-0030's closure and is in the same position as a sqlb.Query in
	// application code.
	Path string

	// Body is the request body, declared in the field vocabulary. Build it with
	// [Body].
	//
	// It is declared rather than reflected from an application type for two
	// reasons. The value of an action is that the verb reaches the TypeScript,
	// Dart, CLI and OpenAPI emitters, and those read this declaration — a body
	// sqlb cannot see produces a client method typed `unknown`, which is the
	// drift this feature exists to remove. And reflecting an application struct
	// would invert the dependency, since models are generated *from* the schema.
	//
	// Leaving it empty is normal: most verbs carry nothing. The generated input
	// type is still emitted, empty, so that adding the first property later
	// does not change the shape of the func the application wrote.
	Body []*Field

	// Writes names the columns the envelope persists after the verb returns,
	// and it is enforced rather than documented: exactly these columns are
	// written, from the row the verb mutated.
	//
	// A verb that has to touch anything else has the transaction and can issue
	// the statement itself. What this buys is that the blast radius of a route
	// is something the OpenAPI document and `sqlb impact` can state — and that
	// the envelope knows to take the row lock, since a declared write set is
	// exactly the case where a read-modify-write can be lost.
	//
	// It must be empty on a collection action, which has no row.
	Writes []string

	// Summary is the one-line description in the OpenAPI document.
	//
	// Left empty it is filled in downstream, as "Complete a task", rather than
	// here: writing that sentence needs the singular of the table name, and a
	// singulariser is a thing codegen has and this package deliberately does
	// not — a wrong guess in a Go type name is cosmetic, and one baked into a
	// declaration is not.
	Summary string

	// Description documents the operation at length.
	Description string
}

Action is a domain verb exposed on a table.

Declare one with TableDef.Action: 

Task.Action(schema.Action{
    Name:   "complete",
    Body:   schema.Body(schema.Text("note").Nullable()),
    Writes: []string{"status", "closed_at"},
})

which serves POST /tasks/{id}/complete and asks the application, at registration, for a func(context.Context, *Task, CompleteTaskInput) error.

func (Action) FullPath added in v0.5.0 

func (a Action) FullPath(resource string) string

FullPath is the action's route: the resource path with the action's own path appended.

func (Action) IsCollection added in v0.5.0 

func (a Action) IsCollection() bool

IsCollection reports whether the action addresses the collection rather than one row — which is to say, whether its path names no id.

type ActionManifest added in v0.5.0 

type ActionManifest struct {
	Name string `json:"name"`
	// Path is the full route, resource path included.
	Path   string `json:"path"`
	Method string `json:"method"`
	// Summary is the one-line description, as it appears in the OpenAPI
	// document.
	Summary string `json:"summary,omitempty"`
	// Body names the request body's properties. An action that declares none
	// carries no body at all, which is not the same as one whose properties
	// happen to be optional.
	Body []ActionProperty `json:"body,omitempty"`
	// Writes names the columns the envelope persists after the verb returns.
	// It is what makes the blast radius of a route readable rather than
	// something to be inferred from a handler.
	Writes []string `json:"writes,omitempty"`
}

ActionManifest documents one declared verb.

type ActionProperty added in v0.5.0 

type ActionProperty struct {
	Name     string   `json:"name"`
	Type     string   `json:"type"`
	Nullable bool     `json:"nullable,omitempty"`
	Enum     []string `json:"enum,omitempty"`
}

ActionProperty is one property of an action's request body.

type Check 

type Check struct {
	Name string
	Expr string
}

Check is a table-level check constraint.

type ColumnManifest 

type ColumnManifest struct {
	Name string `json:"name"`
	// Type names the element type of an array column, with Array set beside
	// it — the same split the declaration uses, so a consumer reading the
	// manifest sees the enum values and the varchar length attached to the
	// thing that has them.
	Type         string       `json:"type"`
	Array        bool         `json:"array,omitempty"`
	GoType       string       `json:"goType"`
	Nullable     bool         `json:"nullable,omitempty"`
	Comment      string       `json:"comment,omitempty"`
	Enum         []string     `json:"enum,omitempty"`
	HasDefault   bool         `json:"hasDefault,omitempty"`
	ReadOnly     bool         `json:"readOnly,omitempty"`
	Immutable    bool         `json:"immutable,omitempty"`
	Capabilities []string     `json:"capabilities,omitempty"`
	References   *RefManifest `json:"references,omitempty"`

	// Obligations, kept out of Capabilities because a capability is something
	// a request may reach and these are things the server must have done. A
	// client generator has no use for either; a reader auditing the boundary
	// has.
	Scoped     bool `json:"scoped,omitempty"`
	SoftDelete bool `json:"softDelete,omitempty"`

	// Computed reports that the column is an expression rather than storage.
	// A consumer reading the manifest to decide what a schema edit costs needs
	// the distinction: this column appears in every response and in no
	// migration.
	Computed bool `json:"computed,omitempty"`
	// Needs names the per-request binds the expression takes. It is the
	// obligation half — a resource exposing this column does not mount until a
	// hook supplies each of them — and it is listed for the same reason Scoped
	// is: a reader auditing the boundary wants to see what the server had to
	// have done.
	Needs []string `json:"needs,omitempty"`
}

ColumnManifest describes one column. Hidden columns are omitted entirely rather than listed as hidden: the manifest is publishable, and a name is itself information.

type ComputedExpr added in v0.5.0 

type ComputedExpr struct {
	// contains filtered or unexported fields
}

ComputedExpr is how a computed column is produced. Build one with FromSQL.

It is a type rather than a bare string so that the declaration reads as a choice — today FromSQL is the only one, and ADR-0041 stages a Go-side form as a separate decision rather than an argument that changes meaning.

func FromSQL added in v0.5.0 

func FromSQL(sql string) ComputedExpr

FromSQL computes a column from a SQL expression over the row's own columns.

The expression is raw SQL and nothing parses it: `sqlb generate` refuses the declarations below that are wrong on their face — a Searchable computed column, a volatile Sortable one, a bind count that disagrees with Needs — but a typo inside the SQL reaches Postgres. That is the cost ADR-0024's bar admits here because there is finally a consumer for the annotation, and [sqlb.Builder.Explain] against a real database is what catches it early.

type Default 

type Default struct {
	Raw   string
	Value any
}

Default describes a column default. Raw is emitted verbatim into DDL; Value is emitted as a literal.

func Expr 

func Expr(sql string) *Default

Expr defaults the column to an arbitrary SQL expression.

func GenUUIDv4 

func GenUUIDv4() *Default

GenUUIDv4 defaults the column to a random UUID using pgcrypto.

func GenUUIDv7 

func GenUUIDv7() *Default

GenUUIDv7 defaults the column to a freshly generated UUIDv7.

How this renders depends on the Postgres it is generated for. By default it emits uuid_generate_v7(), which needs the pg_uuidv7 extension — so the generated DDL does not apply to a stock install. Postgres 18 has uuidv7() built in, and migrate.MinPostgres(18) emits that instead, which needs nothing. On an older server without the extension, use GenUUIDv4.

func Now 

func Now() *Default

Now defaults the column to the statement timestamp.

func Value 

func Value(v any) *Default

Value defaults the column to a literal.

type Diagnostic 

type Diagnostic struct {
	Rule     string
	Table    string
	Column   string
	Severity Severity
	Message  string
	// Fix is the concrete change that would resolve it, where there is one.
	Fix string
}

Lint reports schemas that are correct but operationally unwise.

Validate answers "is this schema well-formed?" and returns errors. Lint answers "will this schema behave badly in production?" and returns advice. The distinction matters: a table can pass validation completely and still expose an unindexed filter that sequential-scans a large table on every request, which is the kind of mistake that is invisible in review and obvious at three in the morning.

Diagnostics are advisory. Nothing fails because of them, and a schema may have good reasons to keep one — a filterable column on a table of twenty rows does not need an index.

func (Diagnostic) String 

func (d Diagnostic) String() string

type Diagnostics 

type Diagnostics []Diagnostic

Diagnostics is an ordered set of lint results.

func Lint 

func Lint() Diagnostics

Lint checks the default registry.

func (Diagnostics) String 

func (ds Diagnostics) String() string

func (Diagnostics) Warnings 

func (ds Diagnostics) Warnings() Diagnostics

Warnings returns only the warn-level diagnostics, for callers that want to fail a build on those but tolerate info.

type Error 

type Error struct {
	Table  string
	Column string
	Msg    string
}

Error is a single schema validation failure, located at a table and optionally a column.

func (Error) Error 

func (e Error) Error() string

type Field 

type Field struct {
	// contains filtered or unexported fields
}

Field is a column under construction. Its methods are chainable setters, so the DSL reads as a declaration: 

schema.Text("email").Unique().Searchable()

Code generators read the result through Desc.

func BigInt 

func BigInt(name string) *Field

func Body added in v0.5.0 

func Body(specs ...FieldSpec) []*Field

Body builds an action's request body from field declarations. 

Body: schema.Body(
    schema.Text("note").Nullable(),
    schema.Timestamp("completed_at"),
)

The vocabulary is the column vocabulary, deliberately: it is the one the emitters already know how to turn into a TypeScript type, a Dart class, a CLI flag and an OpenAPI schema. Only what describes a *value* applies here — name, type, nullability, enum values, default and comment. The capabilities that describe a column's place in a table (Filterable, PrimaryKey, Ref, Computed, and the rest) have no meaning in a request body and are refused by Validate rather than ignored.

func Bool 

func Bool(name string) *Field

func Bytes 

func Bytes(name string) *Field

func Computed added in v0.5.0 

func Computed(name string, t Type, e ComputedExpr) *Field

Computed declares a derived column: an expression the query renders in place of a column name, rather than a value the table stores. 

schema.Computed("is_overdue", schema.TypeBool,
    schema.FromSQL("due_date < current_date AND open_tasks > 0")).
    Filterable().Sortable()

It is a column everywhere it matters — it lands in the row type, the JSON, the TypeScript and Dart types and the CLI column set, and Hidden, Filterable and Sortable gate it exactly as they gate a stored one. What it is not is storage: it emits no DDL in either direction, Diff does not see it, no insert names it and no update assigns it. ADR-0041 has the shape and the reasons.

What each form may claim

The expression is rendered as written, so a name in it resolves the way Postgres resolves it. In a statement that joins — one with `?expand` in it — a bare column name shared with the joined table is ambiguous and Postgres says so; qualify it with the table's own name when that is a possibility.

A row-local expression may be Filterable and Sortable, since the compiler can put it in a WHERE and an ORDER BY as readily as in the projection: 

schema.Computed("is_overdue", schema.TypeBool,
    schema.FromSQL("due_date < current_date AND open_tasks > 0")).Filterable()

A correlated subquery is projection-only unless Filterable is written out, because a subquery in a WHERE runs once per row — the declaration is the acknowledgement that this was considered: 

schema.Computed("total_tasks", schema.TypeInt,
    schema.FromSQL("(SELECT count(*) FROM tasks t WHERE t.project_id = projects.id)"))

A parameterised expression takes its value from the request. Each `?` binds the key named at the matching position of Needs, and `??` is a literal question mark: 

schema.Computed("is_starred", schema.TypeBool,
    schema.FromSQL("EXISTS (SELECT 1 FROM stars s "+
        "WHERE s.project_id = projects.id AND s.member_id = ?)")).
    Needs("viewer").Filterable()

Needs writes no value, exactly as Field.Scoped writes no predicate. What it does is oblige a hook: rest.Resource refuses to mount the resource until a BeforeQuery hook calls Bind for every key it names. Without that check an unbound expression renders `member_id = NULL`, returns false for every row forever, and looks precisely like a feature that works (ADR-0030).

What it will not accept

Searchable, ever: ?search fans out over text columns with ILIKE, and there is no coherent reading of that over an expression. Sortable over a volatile expression — one reading now() or random() — because a keyset pages on the sort column and an unstable one lets page 1 and page 50 disagree about a row. A default, a primary key, a unique constraint, a reference or an index, all of which are statements about storage. Validate reports each of them.

func Date 

func Date(name string) *Field

func Enum 

func Enum(name string, values ...string) *Field

Enum is a text column constrained to a fixed set of values. Codegen emits a Go string type with one constant per value.

func ExternalRef 

func ExternalRef(relation, target string) *Field

ExternalRef declares a reference to a table this module does not own.

It produces a column named relation+"_id" holding the other side's identifier, and an index to join on — but no FOREIGN KEY, so the two modules can be migrated and deployed independently, and either can be moved to its own database without dropping a constraint: 

// in the billing module, with no import of the tenants module
schema.ExternalRef("tenant", "tenants.id").Filterable()

The target is free text. Resolving it to a real table would require exactly the dependency this exists to avoid, so it is recorded for the manifest and for whoever reads the schema, and not checked.

Such a reference cannot be Expandable: expanding it would join a table this module does not own. Fetch the other side through that module's own API.

relation, not column

The first argument is the *relation* — the column is named after it, with "_id" appended. So ExternalRef("org", …) declares a column called org_id, and ExternalRef("org_id", …) declares one called org_id_id. Use Field.Named if the column is spelled some other way.

func Float 

func Float(name string) *Field

func Int 

func Int(name string) *Field

func JSON 

func JSON(name string) *Field

func Numeric 

func Numeric(name string) *Field

func Ref 

func Ref(name string, target *TableDef) *Field

Ref declares a foreign key to target. The column is named name+"_id" and the relation is named name, so Ref("org", Org) yields column "org_id" reachable as ?expand=org once marked Expandable.

func Text 

func Text(name string) *Field

func Time 

func Time(name string) *Field

func Timestamp 

func Timestamp(name string) *Field

func UUID 

func UUID(name string) *Field

func UUIDv7 

func UUIDv7(name string) *Field

UUIDv7 is the conventional primary key column: a UUID defaulting to a generated, time-ordered v7 value.

func Varchar 

func Varchar(name string, size int) *Field

Varchar is a length-bounded text column.

func Vector added in v0.4.0 

func Vector(name string, dim int) *Field

Vector is a pgvector embedding of dim components.

The dimension is an ordinary Go expression, so it can come from wherever the embedder's width comes from: 

schema.Vector("embedding", ragcfg.Dim)

That is deliberately stricter than reading it from the environment at startup, which is what a project does when the schema cannot hold it: the dimension is fixed when the code is generated, so one binary can no longer serve a 768- and a 1,536-component embedder. What it buys is that the dimension is in the declaration, so `Diff` proposes a migration when it changes instead of a comment asking someone to remember (ADR-0026).

The column is Hidden and not optionally so. An embedding is twenty kilobytes of float that no client has a use for, and serialising one by accident is the kind of mistake that shows up as a bandwidth bill. Go callers reading through the query engine still get it.

A vector is storable and orderable and nothing else yet: there is no index kind, no metric declaration and no REST search operation, which ADR-0026 stages as a second decision to be taken when a corpus outgrows an exact scan. Until then a similarity search is an exact scan over the rows a filter already selected, which is the shape the module this was designed against actually runs.

func (*Field) Array 

func (f *Field) Array() *Field

Array makes the column a one-dimensional Postgres array of the type the constructor named: 

schema.Text("tags").Array().Filterable()
schema.Enum("labels", "red", "green").Array()

The Go field is the plain slice — []string, not a named wrapper — so a model described over an existing sqlc struct can carry one (ADR-0033). Nullable still refers to the column: a NULL array and an empty array are different values, and the Go side spells them nil and []string{}.

Only the scalar element types are permitted, and only one dimension. An array column may not be Sortable or Searchable, and a Filterable one must carry a GIN index; Validate reports each of those.

func (*Field) CheckNamed added in v0.5.0 

func (f *Field) CheckNamed(name string) *Field

CheckNamed pins the name of the CHECK an enum column emits. 

schema.Enum("plan", "free", "pro").CheckNamed("chk_org_plan")

It is a second constraint on the same column, so it has a name of its own rather than sharing ConstraintNamed with a unique constraint or a foreign key. Introspection sets it when the database's name is not the one this package would generate; declaring it by hand is for the same case, reached from the other direction.

func (*Field) Comment 

func (f *Field) Comment(s string) *Field

Comment attaches a description, emitted into DDL and the OpenAPI document.

func (*Field) ConstraintNamed 

func (f *Field) ConstraintNamed(name string) *Field

ConstraintNamed pins the name of the constraint this column declares. Use it when adopting an existing database whose constraint names do not match the ones this package would generate.

func (*Field) Default 

func (f *Field) Default(d *Default) *Field

Default sets the column default.

func (*Field) Desc 

func (f *Field) Desc() *FieldDesc

Desc returns the column description. The pointer aliases the field's own state, so generators must treat it as read-only.

func (*Field) Enforced added in v0.5.0 

func (f *Field) Enforced() *Field

Enforced makes an external reference emit a real FOREIGN KEY. 

schema.ExternalRef("org", "organizations.id").Enforced().Filterable()

It is for the case an incremental adoption always reaches: the database has a live, enforced foreign key, and the table it points at has not been declared yet. Neither existing spelling covers that — Ref needs the target's *TableDef, and a plain ExternalRef emits no constraint, so a schema-vs-database diff reports the live one as something to drop and, if sqlb owned the DDL, would propose actually dropping it (issue #55).

The target is still not resolved: it is a name, and the constraint is emitted against that name. Two forms are accepted — "organizations.id" names the table and the column, and a bare "organizations" means its "id". A module-qualified target ("platform/users.users.id") cannot be enforced, because a constraint has to name a table in this database, and neither can a schema-qualified one, which this spelling has no room for.

What this gives up

Everything ADR-0015 bought by refusing the constraint. Two modules joined by an enforced reference can no longer be migrated or deployed independently, and neither can be moved to its own database without dropping it. That is the right trade when both tables are in one database and the constraint is already there — which is exactly the adoption case — and the wrong one across a module boundary you intend to keep.

Expansion is still refused. A real constraint says the row exists; it does not give this schema the target's columns, so `?expand` has nothing to build a join from.

func (*Field) Expandable 

func (f *Field) Expandable() *Field

Expandable allows a reference to be resolved inline via ?expand.

func (*Field) Filterable 

func (f *Field) Filterable() *Field

Filterable allows the column to be used in REST filter expressions.

func (*Field) Hidden 

func (f *Field) Hidden() *Field

Hidden omits the column from every REST response. Use it for password hashes and similar values that must never leave the process.

func (*Field) Immutable 

func (f *Field) Immutable() *Field

Immutable allows the column to be set at create time only.

func (*Field) Inverse 

func (f *Field) Inverse(name string) *Field

Inverse names the relation from the target's side: the name an author knows its posts by. Declaring it is what makes the reverse relation exist. 

schema.Ref("list", List).Expandable().Inverse("tasks").InverseExpandable()

Read as: a task has a list; a list has tasks; both directions may be expanded. Absent Inverse there is no reverse relation, which is not an error — most references never need one.

One side declares, as it already does for the column, the constraint and the delete action. What the target does gain is a field on its generated struct, because the expanded rows need somewhere to land.

func (*Field) InverseExpandable 

func (f *Field) InverseExpandable(opts ...InverseOption) *Field

InverseExpandable exposes the reverse relation through ?expand on the target's endpoint, and takes the options that decide which children a capped expansion returns: 

schema.Ref("list", List).
    Expandable().
    Inverse("tasks").
    InverseExpandable(schema.ExpandOrder("-created_at"), schema.ExpandLimit(20))

It requires Inverse: a relation with no name cannot be asked for. Exposure is a separate decision from Expandable in the forward direction, because the two are about different endpoints.

func (*Field) Name 

func (f *Field) Name() string

Name is the column name.

func (*Field) Named 

func (f *Field) Named(column string) *Field

Named overrides the column name.

Most columns are named where they are declared, so this is only needed where the name was derived: Ref("org", Org) produces "org_id", and a database that calls it "organisation_uuid" needs 

schema.Ref("org", Org).Named("organisation_uuid")

The relation keeps its own name, so ?expand=org still works.

func (*Field) Needs added in v0.5.0 

func (f *Field) Needs(keys ...string) *Field

Needs names the binds this column's expression takes, in the order its `?` placeholders appear. See Computed.

func (*Field) Nullable 

func (f *Field) Nullable() *Field

Nullable allows SQL NULL. Codegen emits the Go field as a pointer.

func (*Field) OfType 

func (f *Field) OfType(t Type) *Field

OfType overrides the column type, for an external reference whose target is not the conventional UUID.

func (*Field) OnDelete 

func (f *Field) OnDelete(a RefAction) *Field

OnDelete sets the foreign key delete action. It panics if the field is not a reference: that is a schema authoring bug, and failing at init is more useful than failing at request time.

func (*Field) OnUpdate 

func (f *Field) OnUpdate(a RefAction) *Field

OnUpdate sets the foreign key update action.

func (*Field) PrimaryKey 

func (f *Field) PrimaryKey() *Field

PrimaryKey marks the column as the table's primary key. Primary keys are implicitly read-only and filterable.

func (*Field) ReadOnly 

func (f *Field) ReadOnly() *Field

ReadOnly makes the column unwritable through REST.

func (*Field) RenamedFrom 

func (f *Field) RenamedFrom(old string) *Field

RenamedFrom declares that this column used to be called old, so that a generated migration renames it rather than dropping it and adding a new one: 

schema.Text("email_address").RenamedFrom("email")

A rename is indistinguishable from a drop and an add when only the before and after states are known, and inferring one from a similar name and type would destroy data whenever the inference was wrong. So it is declared, never inferred (ADR-0014).

The hint is needed for exactly one release: the migration it produces is generated once, and after that the old name is gone from every database the migration has been applied to. A hint whose old column no longer exists is ignored, so leaving one behind is harmless — but delete it at the next edit, because a stale hint reads as a claim about the current schema that is no longer true.

func (*Field) Scoped 

func (f *Field) Scoped() *Field

Scoped declares that this column confines the table's rows to one tenant, and that every operation the table exposes must be constrained by a hook. 

schema.Ref("workspace", Workspace).Filterable().ReadOnly().Scoped()

Like SoftDelete, it writes no predicate and changes no query. What it changes is what happens when the predicate is missing: [rest.Resource] refuses to mount the resource at startup rather than serving every tenant's rows with a 200 next to them (ADR-0030).

The obligation follows the operations the table exposes, because a BeforeQuery hook constrains what a request can see and says nothing about what it can overwrite by id — a list needs BeforeQuery, an update needs BeforeUpdate, a delete needs BeforeDelete, and a create needs BeforeCreate when the column is ReadOnly and so has no other source than the hook.

The row itself is the tenant on the table the others point at, so there the declaration goes on the primary key: 

schema.UUIDv7("id").PrimaryKey().Scoped()

A table may declare one scope column. Where the confinement cannot be written as a column of this table at all — a membership join, say — declare it on the column the hook does constrain, which is the key it narrows.

func (*Field) Searchable 

func (f *Field) Searchable() *Field

Searchable includes the column in the ?search fan-out. Implies Filterable, since search is a filter over the same column.

func (*Field) Sortable 

func (f *Field) Sortable() *Field

Sortable allows the column to appear in ?sort.

func (*Field) Unique 

func (f *Field) Unique() *Field

Unique adds a single-column unique constraint.

type FieldDesc 

type FieldDesc struct {
	Name string
	// Type names the *element* type when Array is set, and the column type
	// otherwise. Keeping the element rather than fusing the two is what lets
	// the filter parser bind `?tags=has.urgent` as a text value, and what keeps
	// EnumValues and Size attached to something that has them (ADR-0033).
	Type Type
	// Array makes the column a one-dimensional Postgres array of Type.
	Array bool
	Size  int // varchar length; 0 means unbounded
	// Dim is the number of components in a TypeVector column, and is part of
	// the type rather than a constraint on it: Postgres will not store a
	// 768-component value in a vector(1536). Zero for every other type.
	//
	// It is a Go expression at the call site, which is the whole answer to the
	// substitution sentinel a migration file needs otherwise — the dimension
	// wants to be a value and SQL text has nowhere to put one (ADR-0026).
	Dim     int
	Comment string

	Nullable   bool
	PrimaryKey bool
	Unique     bool
	Default    *Default
	EnumValues []string

	// Capabilities. Each is opt-in and gates one specific REST affordance.
	Filterable bool // may be used in a REST filter expression
	Sortable   bool // may appear in ?sort
	Searchable bool // included in the ?search fan-out
	Expandable bool // relation may be pulled in via ?expand (references only)

	// Write protection, enforced by the REST layer. Go code going through the
	// query engine directly is trusted and bypasses these.
	ReadOnly  bool // never settable through REST
	Immutable bool // settable at create, rejected on update
	Hidden    bool // never serialised into a REST response

	// Obligations. Neither of these changes a query. They are read once, at
	// startup, where rest refuses to mount a resource whose declarations have
	// no hook behind them; nothing on the request path reads either one.
	Scoped     bool // every exposed operation must be constrained by a hook
	SoftDelete bool // the column a soft-delete predicate is expected to filter

	// ConstraintName pins the name of the constraint this column declares —
	// its unique constraint, or its foreign key if it is a reference. Set it
	// when adopting an existing database, so that a generated migration
	// recognises the constraint already there instead of dropping and
	// recreating it under a name of its own choosing.
	ConstraintName string

	// CheckName pins the name of the CHECK an enum column emits, which is a
	// second constraint on the same column and so cannot share the field above:
	// a column may be unique *and* an enum, and one name cannot serve both.
	//
	// An enum is text plus a CHECK (ADR-0017), and the check's name is the one
	// thing about it that introspection cannot recover from the expression. Left
	// unpinned, a database whose check is called chk_org_plan is rebuilt with
	// one called orgs_plan_check — so a diff against it proposes dropping and
	// re-adding that constraint on every run, forever (issue #53).
	CheckName string

	// RenamedFrom is the column's previous name, declared for one release so
	// that a migration renames the column instead of dropping and re-adding
	// it. Nothing else reads it.
	RenamedFrom string

	// Expr is the SQL a computed column renders as, in place of its name, and
	// it is the one thing about a column that no struct tag can carry: a tag is
	// a comma-separated list and SQL is not. Codegen writes it into a
	// ComputedColumns method instead (ADR-0041).
	//
	// A column with an expression stores nothing. It emits no DDL in either
	// direction, no insert names it and no update sets it — and it is a column
	// everywhere else, so Hidden hides it, Filterable gates it, and it lands in
	// the row type, the JSON, the client types and the CLI like any other.
	Expr string
	// Needs names the binds Expr's `?` placeholders take, in order. A computed
	// column with none is row-local. One with a bind is answered per request,
	// and the value arrives through Builder.Bind — which rest refuses to mount
	// a resource without.
	Needs []string

	Ref *Reference
	// contains filtered or unexported fields
}

FieldDesc is the resolved description of a column: everything a generator or the runtime needs to know about it.

func (*FieldDesc) Capabilities 

func (d *FieldDesc) Capabilities() string

Capabilities renders the column's capabilities as the comma-separated body of the `sqlb` struct tag that the runtime engine reads back.

Example

The capabilities render into the `sqlb` struct tag that codegen writes onto the model, which is how the runtime engine reads them back without importing this package. That import direction is what keeps the engine usable without the DSL. 

package main

import (
	"fmt"

	"github.com/jryannel/sqlb/schema"
)

func main() {
	fmt.Println(schema.Text("email").Unique().Searchable().Desc().Capabilities())
	fmt.Println(schema.Text("secret").Hidden().Desc().Capabilities())
	fmt.Println(schema.BigInt("views").Filterable().Sortable().ReadOnly().Desc().Capabilities())
}

Output:
filter,search
hidden
filter,sort,readonly

func (*FieldDesc) Computed added in v0.5.0 

func (d *FieldDesc) Computed() bool

Computed reports whether the column is an expression rather than storage. The DDL emitters read it to skip the column, and Diff reads it to not see it at all.

func (*FieldDesc) GoType 

func (d *FieldDesc) GoType() string

GoType is the Go type codegen emits for this column.

An array is the plain slice of its element type, nullable or not: a nil slice already says NULL and an empty one says {}, so a pointer would add a third spelling for a distinction that only has two.

A nullable bytea is the same argument and stays []byte: nil is already how a slice says NULL, and a pointer would add a second spelling for it.

jsonb used to be excluded alongside it, on the strength of the resemblance — json.RawMessage is a slice of bytes too. The resemblance is where it ends. []byte says NULL by being nil because that is what it *is*; json.RawMessage is a document type whose nullability the model otherwise never states, which left a nullable jsonb as the one column whose generated type did not say it could be NULL.

It was also, until sqlb took pgx as a dependency (ADR-0040), unreadable. database/sql's convertAssign resolves a scan destination by concrete type: it carries a `case *[]byte` that stores NULL as a nil slice, and json.RawMessage is a named type over []byte that matches neither that case nor any other, so a NULL fell out the bottom as "unsupported Scan, storing driver.Value type <nil>". pgx has no such gap and scans NULL into a bare json.RawMessage as nil, so on sqlb's own path this is now consistency rather than a repair — but it is consistency the generated struct keeps when it is read by anything else, database/sql included.

func (*FieldDesc) IndexWanted 

func (d *FieldDesc) IndexWanted() bool

IndexWanted reports whether this column implicitly asked for an index. An external reference does, since a soft foreign key exists to be joined on and one without an index scans the table.

func (*FieldDesc) Placeholders added in v0.5.0 

func (d *FieldDesc) Placeholders() int

Placeholders counts the binds a computed expression takes, treating `??` as the escaped literal that Raw does.

func (*FieldDesc) Volatile added in v0.5.0 

func (d *FieldDesc) Volatile() bool

Volatile reports whether a computed expression reads something that does not hold still.

type FieldSpec 

type FieldSpec interface {
	// contains filtered or unexported methods
}

FieldSpec is anything contributing columns to a table. Both *Field and the grouped helpers (Timestamps, SoftDelete) implement it, so they mix freely in a single Table call.

type Group 

type Group []*Field

Group is an ordered set of fields inserted into a table as a unit. Use it to factor recurring column sets out of a schema.

func SoftDelete 

func SoftDelete() Group

SoftDelete adds a nullable deleted_at column, and nothing else. Nothing on the request path reads the column: the name is not load-bearing anywhere below this line, and declaring the group changes no query.

What it does do is oblige the table to have a BeforeQuery hook. A table that declares a soft delete and filters nothing returns deleted rows from every list endpoint, so [rest.Resource] refuses to mount one whose reads no hook constrains (ADR-0030). The refusal is at startup and it checks only that a hook exists — writing the predicate is still the caller's, exactly as below.

Filtering the deleted rows out is a BeforeQuery registration, which is the seam that reaches generated REST handlers as well as queries written by hand (ADR-0008): 

sqlb.On[Post]().BeforeQuery(func(_ context.Context, q *sqlb.Builder[Post]) error {
    q.Where(sqlb.F("deleted_at").IsNull())
    return nil
})

Serving DELETE as an update to the column is the caller's too, and BeforeDelete cannot do it — that hook receives a *Delete and can abort or amend the statement, not turn it into an UPDATE. A table that means deletes to be soft should leave OpDelete out of its Expose and route the endpoint itself.

func Timestamps 

func Timestamps() Group

Timestamps is the created_at / updated_at pair, both defaulting to now().

type Index 

type Index struct {
	Name    string
	Columns []string
	Unique  bool
	Method  string // "btree", "gin", ...; empty means the dialect default
	Where   string // optional partial-index predicate

	// Opclasses names the operator class each column is indexed under, keyed by
	// column name. An absent entry takes the type's default.
	//
	// For most indexes an operator class is a tuning decision. For some it is
	// the whole meaning: pgvector's `hnsw` has *no* default class, because the
	// class is what selects the distance function, so an index emitted without
	// one is rejected outright —
	//
	//	ERROR: data type vector has no default operator class for access method "hnsw"
	//
	// — and a schema that could not express it could not describe its own
	// database (issue #53).
	//
	//	AddIndex(schema.Index{
	//	    Name:      "idx_chunks_embedding",
	//	    Columns:   []string{"embedding"},
	//	    Method:    "hnsw",
	//	    Opclasses: map[string]string{"embedding": "vector_cosine_ops"},
	//	    With:      map[string]string{"m": "16", "ef_construction": "64"},
	//	})
	Opclasses map[string]string

	// With is the index's storage parameters — `WITH (m = 16)`. Rendered in
	// sorted key order, because a map has none and a migration that reorders
	// its own DDL between runs is a diff nobody can read.
	With map[string]string
}

Index is a secondary index.

type IndexManifest 

type IndexManifest struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique,omitempty"`
	Method  string   `json:"method,omitempty"`
}

IndexManifest describes a secondary index.

type InverseManifest 

type InverseManifest struct {
	Name   string `json:"name"`
	Table  string `json:"table"`
	Column string `json:"column"`
	// Order is the column an expansion sorts the collected rows by, with a
	// leading "-" for descending. Empty means the primary key.
	Order string `json:"order,omitempty"`
	// Limit is how many rows one expansion returns at most, with the default
	// already resolved: a client reading this is never left to guess the cap.
	// Past it the response reports has_more and the caller pages the collected
	// table's own endpoint by Column.
	Limit int `json:"limit,omitempty"`
	// Expandable reports whether ?expand on this table may ask for it. A
	// relation that is named but not expandable is still described here,
	// because the relationship exists whether or not this endpoint serves it.
	Expandable bool `json:"expandable"`
}

InverseManifest describes one reverse relation from the target's side.

type InverseOption 

type InverseOption func(*Reference)

InverseOption adjusts an expanded collection.

func ExpandLimit 

func ExpandLimit(n int) InverseOption

ExpandLimit caps how many children an expansion returns; the default is 50. Past the cap the response reports has_more and the caller follows the child's own endpoint, filtered by this foreign key — which is why that column wants to be Filterable, and why Lint says so when it is not.

func ExpandOrder 

func ExpandOrder(column string) InverseOption

ExpandOrder orders an expanded collection by a column of the referencing table, with a leading "-" for descending — the spelling ?sort already uses. The primary key is appended as a tiebreaker, because under a cap a non-total order decides which children the caller never sees.

type InverseRelation 

type InverseRelation struct {
	Name       string    // the name ?expand uses on the target
	Table      *TableDef // the table whose rows are collected
	Column     string    // that table's foreign key column
	Order      string    // ordering column, with a leading "-" for descending
	Limit      int       // cap as declared; zero means DefaultExpandLimit
	Expandable bool      // reachable through ?expand on the target
}

InverseRelation is a reverse relation seen from the target's side: the rows of another table that point at this one, and the name this table knows them by.

It is derived rather than declared here — the declaration lives on the referencing column, which is the side that already owns the constraint. What the target gains is a field on its generated struct and, if the reference exposed it, a name in its ?expand vocabulary. ADR-0022.

func (InverseRelation) Cap 

func (i InverseRelation) Cap() int

Cap is how many rows one expansion returns at most, with the default resolved. Anything published — the manifest, a generated tag — uses this rather than Limit, so a caller is never left to guess the number.

type Manifest 

type Manifest struct {
	Version   string          `json:"version"`
	Module    string          `json:"module,omitempty"`
	Tables    []TableManifest `json:"tables"`
	Operators []OperatorDoc   `json:"filterOperators"`
	Params    []ParamDoc      `json:"reservedParams"`
}

Manifest is a machine-readable description of a schema: every table, every column, and — the part that matters most — exactly what a client may filter, sort, search and expand on each exposed resource.

It reports capabilities that work, not capabilities that are declared. The two coincide today; where they ever diverge again, this file is what has to keep telling the truth.

It exists because reading a Go DSL to answer "what can I query here?" is a poor interface for a program. The manifest answers it directly, in one file, with worked example requests. Emit it next to the generated code and point tooling at it.

func BuildManifest 

func BuildManifest() *Manifest

BuildManifest describes the default registry.

func (*Manifest) JSON 

func (m *Manifest) JSON() ([]byte, error)

JSON renders the manifest.

type Op 

type Op uint8

Op is a bitmask of the REST operations a table exposes. 

const (
	OpCreate Op = 1 << iota
	OpRead      // GET /resource/{id}
	OpUpdate
	OpDelete
	OpList // GET /resource with filter, sort, search, pagination
)

func (Op) Has 

func (o Op) Has(op Op) bool

Has reports whether the mask contains op.

func (Op) String 

func (o Op) String() string

String renders the mask for diagnostics.

type OperatorDoc 

type OperatorDoc struct {
	Name    string `json:"name"`
	Form    string `json:"form"`
	Applies string `json:"applies"`
}

OperatorDoc documents one filter operator.

type ParamDoc 

type ParamDoc struct {
	Name string `json:"name"`
	Form string `json:"form"`
}

ParamDoc documents one reserved query parameter.

type REST 

type REST struct {
	// Path is the collection path, e.g. "/users". Defaults to "/"+table name.
	Path string
	// Ops is the set of exposed operations.
	Ops Op
	// DefaultPageSize applies when the request omits a page size. Zero means
	// the package default.
	DefaultPageSize int
	// MaxPageSize caps the page size a client may request. Zero means the
	// package default. This is a hard ceiling, not a hint.
	MaxPageSize int
	// MaxFilters caps how many filter predicates one request may carry, which
	// bounds the cost of a single query. Zero means the package default.
	MaxFilters int
	// Tag groups the resource's operations in the OpenAPI document. Defaults
	// to the table name.
	Tag string
}

REST describes how a table is exposed over HTTP.

type RESTManifest 

type RESTManifest struct {
	Path            string   `json:"path"`
	Operations      []string `json:"operations"`
	DefaultPageSize int      `json:"defaultPageSize"`
	MaxPageSize     int      `json:"maxPageSize"`
	MaxFilters      int      `json:"maxFilters,omitempty"`

	Filterable []string `json:"filterable"`
	Sortable   []string `json:"sortable"`
	Searchable []string `json:"searchable"`

	// Expandable names the relations ?expand may pull in. Each is the relation
	// name, not the foreign key column: ?expand=list, not ?expand=list_id.
	//
	// Only internal references appear. An ExternalRef crosses a module
	// boundary, which is exactly the join this schema will not perform.
	Expandable []string `json:"expandable,omitempty"`

	// Actions are the domain verbs the table declares. Without them an agent
	// reading this document sees a CRUD-only API and concludes that completing
	// a task means PATCHing its status — which is the transition the verb
	// exists to own (ADR-0043).
	Actions []ActionManifest `json:"actions,omitempty"`

	Examples []string `json:"examples,omitempty"`
}

RESTManifest is the queryable surface of an exposed table: the single most useful thing in the document.

type RefAction added in v0.5.0 

type RefAction string

RefAction is a foreign key referential action.

It was spelled Action until a table needed that noun for a domain verb (TableDef.Action, ADR-0043). Two meanings of "action" in one package is the kind of ambiguity that outlives everyone who could explain it, and this is the side almost nobody writes by name — the constants below carry the meaning at every call site. 

const (
	NoAction   RefAction = "NO ACTION"
	Restrict   RefAction = "RESTRICT"
	Cascade    RefAction = "CASCADE"
	SetNull    RefAction = "SET NULL"
	SetDefault RefAction = "SET DEFAULT"
)

type RefManifest 

type RefManifest struct {
	Relation string `json:"relation"`
	Table    string `json:"table,omitempty"`
	Column   string `json:"column,omitempty"`
	OnDelete string `json:"onDelete,omitempty"`
	External bool   `json:"external,omitempty"`
	Target   string `json:"target,omitempty"`
	Enforced bool   `json:"enforced"`
}

RefManifest describes a relationship. External references carry a target string and no enforced constraint, so a reader can see the relationship even though the database does not.

type Reference 

type Reference struct {
	Name     string // relation name, e.g. "org" for column "org_id"
	Table    *TableDef
	Column   string // referenced column; defaults to the target primary key
	OnDelete RefAction
	OnUpdate RefAction

	// External marks a reference across a module boundary. No FOREIGN KEY is
	// emitted for one, so the modules stay independently deployable and
	// independently migratable. Referential integrity becomes the
	// application's responsibility, which is the trade a module architecture
	// is already making everywhere else.
	External bool
	// Target names what is referenced, for documentation and for the
	// manifest: "tenants.id", or "platform/users.users.id". It is free text,
	// deliberately — resolving it would require the dependency this is
	// designed to avoid.
	Target string
	// Enforced turns an external reference into a real FOREIGN KEY to the
	// table Target names, without resolving that table's declaration. It is
	// the case an incremental adoption lives in: the database has a live,
	// enforced constraint and the table it points at has not been declared yet
	// (issue #55). See Field.Enforced.
	Enforced bool

	// Inverse is the name the target knows this relation by, and declaring it
	// is what makes the reverse relation exist at all.
	//
	// It cannot be derived. Two references from posts to authors — the writer
	// and the reviewer — would both derive to "posts" on the far side, and an
	// author's posts are not the posts an author reviewed. The distinction
	// exists only in the head of whoever wrote the schema, so the schema is
	// where it has to be written. ADR-0022.
	Inverse string
	// InverseExpandable exposes the reverse relation through ?expand on the
	// target's endpoint. It is a separate decision from Expandable, about a
	// different endpoint, and neither implies the other — ADR-0006.
	InverseExpandable bool
	// InverseOrder is the column an expanded collection is ordered by, with a
	// leading "-" for descending. It names a column of *this* table, since
	// these are the rows being collected. Empty means the primary key.
	InverseOrder string
	// InverseLimit caps an expanded collection. Zero takes sqlb's default.
	InverseLimit int
}

Reference describes a relationship to another table.

A reference is either internal — a real foreign key to a table in the same registry — or external, which is a column holding another module's identifier with no database-level constraint behind it.

func (*Reference) EnforcedTarget added in v0.5.0 

func (r *Reference) EnforcedTarget() (table, column string, ok bool)

EnforcedTarget resolves an enforced external reference's target into the table and column a FOREIGN KEY names.

"organizations.id" is a table and a column; a bare "organizations" is that table's "id", which is the convention every other part of this DSL already assumes. Anything else — a module-qualified target, an empty one, more than one dot — reports false, and Validate turns that into an error naming the two forms rather than emitting a constraint against a guess.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds a set of table declarations.

A registry is also the unit of module isolation. Independent modules — fx modules, or any other arrangement where one package must not import another — each declare into their own registry, so two modules may both own a table called "events" without colliding.

func DefaultRegistry 

func DefaultRegistry() *Registry

DefaultRegistry returns the registry that Table populates.

func NewModule 

func NewModule(name string) *Registry

NewModule returns a registry whose tables are all prefixed with the module name, so that table ownership is visible in the database and cannot be forgotten: 

var Billing = schema.NewModule("billing")
var Invoice = Billing.Table("invoices", …)   // → billing_invoices

The prefix is applied by the registry rather than written into each declaration, which is the point: a convention that has to be repeated at every call site is a convention that drifts.

Declarations still use the local name, so a table moving between modules changes one line.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry returns an empty registry. Most schemas use the default one via the package-level functions.

func (*Registry) Add 

func (r *Registry) Add(t *TableDef)

Add registers a table. A duplicate name panics: two tables with the same name is an authoring error that would otherwise surface as confusing DDL.

func (*Registry) BuildManifest 

func (r *Registry) BuildManifest() *Manifest

BuildManifest describes every table in the registry.

func (*Registry) Exposed 

func (r *Registry) Exposed() []*TableDef

Exposed returns the tables with a REST surface, sorted by name.

func (*Registry) Get 

func (r *Registry) Get(name string) *TableDef

Get returns the named table, or nil.

func (*Registry) Inverses 

func (r *Registry) Inverses(t *TableDef) []InverseRelation

Inverses returns the reverse relations pointing at t, in a deterministic order: by referencing table, then by declaration order within it.

func (*Registry) Lint 

func (r *Registry) Lint() Diagnostics

Lint checks the registry.

Example

Lint reports schema problems that compile fine but produce a bad database or a bad API — an unindexed filterable column, a table exposed without a primary key. It is worth running from a test, so the schema is checked in CI. 

package main

import (
	"fmt"

	"github.com/jryannel/sqlb/schema"
)

func main() {
	reg := schema.NewRegistry()
	reg.Table("events",
		schema.UUIDv7("id").PrimaryKey(),
		// Filterable, but nothing indexes it: every filtered request is a
		// sequential scan.
		schema.Text("kind").Filterable(),
	).
		Expose(schema.REST{Ops: schema.OpList})

	for _, d := range reg.Lint() {
		fmt.Println(d)
	}
}

Output:
[warn] unindexed-filter: events.kind: column is filterable but is not the leading column of any index, so filtering on it scans the table
    fix: add .Index("kind") to the table, or drop .Filterable() from the column
[info] list-without-sort: events: list endpoint has no sortable column, so every client gets the same primary-key order and none can ask for another
    fix: mark at least one column .Sortable(), conventionally created_at
[info] no-max-page-size: events: no MaxPageSize, so the package default applies as the hard ceiling
    fix: set MaxPageSize on the REST exposure to a value this table can serve

func (*Registry) Module 

func (r *Registry) Module() string

Module returns the module name, or "" for a registry that is not a module.

func (*Registry) Qualify 

func (r *Registry) Qualify(local string) string

Qualify renders a local table name as this registry would store it.

func (*Registry) Table 

func (r *Registry) Table(name string, specs ...FieldSpec) *TableDef

Table declares a table in a specific registry. Use it to keep a schema isolated from the default one, which is mainly what tests want.

func (*Registry) Tables 

func (r *Registry) Tables() []*TableDef

Tables returns every registered table, sorted by name so that generated output is deterministic across runs.

func (*Registry) Validate 

func (r *Registry) Validate() error

Validate checks the registry for authoring mistakes and returns every problem it finds, joined into a single error. Reporting all of them at once rather than stopping at the first keeps the edit-generate loop short.

type Severity 

type Severity string

Severity ranks how much a diagnostic should be believed. 

const (
	// SeverityWarn is a problem that will very likely bite in production.
	SeverityWarn Severity = "warn"
	// SeverityInfo is worth a look but is often fine.
	SeverityInfo Severity = "info"
)

type TableDef 

type TableDef struct {
	// contains filtered or unexported fields
}

TableDef is a table declaration. Build one with Table, which also registers it in the default registry.

func Get 

func Get(name string) *TableDef

Get returns the named table from the default registry.

func Table 

func Table(name string, specs ...FieldSpec) *TableDef

Table declares a table and registers it in the default registry. This is the form a schema file uses.

Example

A schema is written as ordinary Go values, which is what lets one declaration be the source of truth for migrations, models, REST handlers and OpenAPI.

Capabilities are opt-in per column: a column that does not declare one cannot be reached through it. That is the difference between this and exposing the database — the failure is a 400 naming the allowed columns, not a leak. 

package main

import (
	"fmt"

	"github.com/jryannel/sqlb/schema"
)

func main() {
	// A registry of its own keeps this example out of the default one. A schema
	// file would call schema.Table, which registers into the default registry.
	reg := schema.NewRegistry()

	posts := reg.Table("posts",
		schema.UUIDv7("id").PrimaryKey(),
		schema.Text("title").Searchable().Sortable(),
		schema.Enum("status", "draft", "review", "published").
			Default(schema.Value("draft")).
			Filterable().
			Sortable(),
		// Readable by Go code, but never serialised into a response — and not
		// filterable either, since a filterable secret can be recovered by
		// probing it one value at a time.
		schema.Text("password_hash").Hidden(),
		schema.Timestamps(),
	).
		Index("status").
		Expose(schema.REST{Ops: schema.CRUD | schema.OpList, MaxPageSize: 100})

	for _, f := range posts.Fields() {
		d := f.Desc()
		fmt.Printf("%-13s %-11s %s\n", d.Name, d.Type, d.Capabilities())
	}
	fmt.Println("path:", posts.Rest().Path)
	fmt.Println("ops: ", posts.Rest().Ops)

}

Output:
id            uuid        pk,default,filter,readonly
title         text        filter,sort,search
status        enum        default,filter,sort
password_hash text        hidden
created_at    timestamptz default,sort,readonly
updated_at    timestamptz default,sort,readonly
path: /posts
ops:  create|read|update|delete|list

func Tables 

func Tables() []*TableDef

Tables returns every table in the default registry.

func (*TableDef) Action added in v0.5.0 

func (t *TableDef) Action(a Action) *TableDef

Action declares a domain verb on the table and returns the table, so that declarations chain the way Expose and AddIndex already do.

The table must also be exposed: an action is a route on the resource, and a table with no resource has nowhere to put one.

func (*TableDef) Actions added in v0.5.0 

func (t *TableDef) Actions() []Action

Actions returns the table's declared verbs, in declaration order.

func (*TableDef) AddIndex 

func (t *TableDef) AddIndex(idx Index) *TableDef

AddIndex adds a fully specified index, for cases the shorthands do not cover such as GIN indexes or partial indexes.

func (*TableDef) Check 

func (t *TableDef) Check(name, expr string) *TableDef

Check adds a table-level check constraint.

func (*TableDef) Checks 

func (t *TableDef) Checks() []Check

Checks returns the declared check constraints.

func (*TableDef) Comment 

func (t *TableDef) Comment() string

Comment returns the table description.

func (*TableDef) Describe 

func (t *TableDef) Describe(s string) *TableDef

Describe attaches a table description, emitted into DDL and OpenAPI.

func (*TableDef) Expose 

func (t *TableDef) Expose(r REST) *TableDef

Expose publishes the table over HTTP. Without this call the table is reachable from Go code but has no REST surface at all.

func (*TableDef) Field 

func (t *TableDef) Field(name string) *Field

Field returns the named column, or nil.

func (*TableDef) Fields 

func (t *TableDef) Fields() []*Field

Fields returns the table's columns in declaration order, computed ones included: they are columns to every consumer that describes the row — the model, the clients, the CLI, the OpenAPI document.

func (*TableDef) Index 

func (t *TableDef) Index(columns ...string) *TableDef

Index adds a secondary index over the given columns, named by convention: posts_org_id_idx. Use TableDef.IndexNamed when the name matters.

func (*TableDef) IndexNamed added in v0.5.0 

func (t *TableDef) IndexNamed(name string, columns ...string) *TableDef

IndexNamed adds a secondary index under a name you choose, rather than the one the convention would derive. 

t.IndexNamed("idx_projects_org_id", "org_id")

It exists for adopting a database somebody else's tool built. A declared index whose name does not match the live one is a rename, and a schema of any size turns "declare the tables sqlb already agrees with" into "rename every index in the database" — which is a migration nobody asked for, on a database where it is the least welcome (issue #57).

An index name is not always inert

Postgres reports a violated constraint by name, and matching that name is the standard way to tell one unique violation from another: 

pgErr.Code == "23505" && pgErr.ConstraintName == "idx_projects_org_code"

So renaming an index can turn a handled collision — retry with the next suffix — into an unhandled 500, without touching the code that handles it. That is the reason this is a declaration rather than a lint: the schema has to be able to say what the name *is*, not merely prefer it.

func (*TableDef) Indexes 

func (t *TableDef) Indexes() []Index

Indexes returns the table's secondary indexes: the declared ones, and the implicit index an external reference asks for when nothing else already covers its column.

func (*TableDef) LocalName 

func (t *TableDef) LocalName() string

LocalName is the name as declared, without the module prefix.

func (*TableDef) Module 

func (t *TableDef) Module() string

Module is the owning module name, or "" if the table is not in one.

func (*TableDef) Name 

func (t *TableDef) Name() string

Name is the table's storage name, including any module prefix. This is the name that reaches SQL.

func (*TableDef) PrimaryKey 

func (t *TableDef) PrimaryKey() *Field

PrimaryKey returns the primary key column, or nil if the table declares none.

func (*TableDef) PrimaryKeyName 

func (t *TableDef) PrimaryKeyName() string

PrimaryKeyName returns the pinned primary key constraint name, if any.

func (*TableDef) PrimaryKeyNamed 

func (t *TableDef) PrimaryKeyNamed(name string) *TableDef

PrimaryKeyNamed pins the primary key constraint name, for adopting an existing database whose constraint is not called <table>_pkey.

func (*TableDef) Relations 

func (t *TableDef) Relations() []*Field

Relations returns the table's reference columns.

func (*TableDef) RenamedFrom 

func (t *TableDef) RenamedFrom(local string) *TableDef

RenamedFrom declares that this table used to be called local, so that a generated migration renames it rather than dropping it and creating a new one. See Field.RenamedFrom for why a rename is declared rather than inferred, and for how long the hint is needed.

The old name is local, without the module prefix, and is qualified with the same prefix as the current one — so this renames a table within a module, not between modules. Moving a table between modules changes which registry declares it, and is a drop and a create until something asks for otherwise.

func (*TableDef) RenamedFromName 

func (t *TableDef) RenamedFromName() string

RenamedFromName returns the table's previous storage name, or "".

func (*TableDef) ReplaceCheckExpr 

func (t *TableDef) ReplaceCheckExpr(name, expr string) bool

ReplaceCheckExpr rewrites the expression of an already-declared check, and reports whether there was one by that name.

This exists for one caller and it is worth naming, because a setter on a declaration is otherwise a smell. Postgres does not store a CHECK expression as it was written: it stores a parse tree, and hands back a normalised spelling — fully parenthesised, with explicit casts on literals. So a registry read back by introspect and a registry declared here disagree about every check they have in common, and a diff between them proposes dropping and re-adding each one forever (issue #24).

The only reliable way to compare them is to put the declared expression through the same normalisation, which means asking a Postgres. That is what shadow.NormalizeChecks does, and this is how it writes the answer back. Comparing the two spellings textually instead was rejected: stripping parentheses can make two genuinely different expressions look equal, and a diff that reports "unchanged" for a changed constraint is silently wrong, where churn is merely loud.

func (*TableDef) Rest 

func (t *TableDef) Rest() *REST

Rest returns the REST exposure, or nil if the table is not exposed.

func (*TableDef) StoredField added in v0.5.0 

func (t *TableDef) StoredField(name string) *Field

StoredField returns the named column if the database holds it, and nil for a computed one — which is what a migration wants: turning a stored column into a computed one means the storage goes away, and a diff that saw the declaration would leave the old column behind forever.

func (*TableDef) StoredFields added in v0.5.0 

func (t *TableDef) StoredFields() []*Field

StoredFields returns the columns the database actually holds.

It is what the DDL and the diff read, and the only distinction either of them has to make about a computed column: an expression has no type to declare, no default to write and no ALTER to propose, so a migration that saw one would propose creating a column that must not exist and then propose dropping it again on the next run (ADR-0041).

func (*TableDef) UniqueIndex 

func (t *TableDef) UniqueIndex(columns ...string) *TableDef

UniqueIndex adds a composite unique index, named by convention: posts_org_id_slug_uniq. Use TableDef.UniqueIndexNamed when the name matters, which for a unique index it more often does — see below.

func (*TableDef) UniqueIndexNamed added in v0.5.0 

func (t *TableDef) UniqueIndexNamed(name string, columns ...string) *TableDef

UniqueIndexNamed adds a composite unique index under a name you choose. See TableDef.IndexNamed, and note that a unique index is the kind whose name an application is most likely to be matching on.

type TableManifest 

type TableManifest struct {
	Name       string           `json:"name"`
	Module     string           `json:"module,omitempty"`
	LocalName  string           `json:"localName,omitempty"`
	Comment    string           `json:"comment,omitempty"`
	PrimaryKey string           `json:"primaryKey,omitempty"`
	Columns    []ColumnManifest `json:"columns"`
	Indexes    []IndexManifest  `json:"indexes,omitempty"`

	// CollectedBy describes the reverse relations pointing at this table: the
	// rows of another table that this one collects, and the name it knows them
	// by. Declared on the referencing side, which is where the column and the
	// constraint already live, so reading this table alone would otherwise not
	// show that its endpoint has them. ADR-0022.
	CollectedBy []InverseManifest `json:"collectedBy,omitempty"`

	REST *RESTManifest `json:"rest,omitempty"`
}

TableManifest describes one table.

type Type 

type Type string

Type is the logical column type. Dialects map these onto concrete SQL types. 

const (
	TypeText      Type = "text"
	TypeVarchar   Type = "varchar"
	TypeInt       Type = "int"
	TypeBigInt    Type = "bigint"
	TypeFloat     Type = "float"
	TypeNumeric   Type = "numeric"
	TypeBool      Type = "bool"
	TypeUUID      Type = "uuid"
	TypeTimestamp Type = "timestamptz"
	TypeDate      Type = "date"
	TypeTime      Type = "time"
	TypeJSON      Type = "jsonb"
	TypeBytes     Type = "bytea"
	TypeEnum      Type = "enum"
	// TypeVector is a pgvector embedding. Unlike every other type here it
	// carries a parameter that is part of the type rather than a constraint on
	// it — a vector(768) and a vector(1536) are different types to Postgres,
	// and the dimension is FieldDesc.Dim (ADR-0026).
	TypeVector Type = "vector"
)

func Types added in v0.5.0 

func Types() []Type

Types is every logical column type, in declaration order.

It exists so that a consumer which must handle all of them can be checked against the list rather than against its author's memory. That is not hypothetical: `introspect` imported a vector column and `RenderSchema` could not write one back out, so the bootstrap that turns a 69-table database into 69 declarations to review failed on the one type the rest of the toolchain already handled (issue #53). A test walks this list now.

func (Type) GoType 

func (t Type) GoType() string

GoType returns the Go type that codegen emits for a non-null column of this type. Nullable columns are emitted as pointers to it.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.