storm

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: MIT Imports: 14 Imported by: 0

README

storm

Every other Go ORM builds SQL at runtime. storm builds it at compile time — including the dynamic queries.

An embeddable ORM for PostgreSQL and Go. Generated, not reflected. Imported, not deployed. Zero CGO; the driver lives behind a four-method port.

Model-first: one plain Go struct per table — no tags, no DSL. Everything the type cannot say goes in a Schema method using field pointers, so the editor enforces names and refactors follow them. storm emits reviewable migrations and never applies DDL.

Renamed from raorm (2026-08-27). The module path is now github.com/gsoultan/storm, and v0.2.0 is the first usable version under it — GitHub's redirect makes the older tags visible under this path, but their go.mod declares the old one and Go rejects the mismatch. v0.1.x remains available as github.com/gsoultan/raorm. See CHANGELOG.md for the two-step migration.

Status

v0.3.0 is tagged. The read path, migrations, relations, writes, the typed escape hatch and the tooling gate are built, benchmarked and hardened; the first adopter migrated a whole bounded context (M6) and runs on the published module. v0.3.0 adds model discovery, declared aggregations and joins, full-text search, range types and typed constraint errors — and a MySQL DDL back end that is not a runtime target (ADR-0007). The milestone log with every exit gate is docs/PLAN.md, and what would still stop a team adopting this is written down, with gates, in docs/PRODUCTION-READINESS.md.

Every claim below is a test or a benchmark in this repository. The quickstart is executable: examples/blog runs as a test in CI, so it cannot drift from the library the way prose does.

The sixty-second tour

// The model: a plain struct. *T = nullable, Xxx Yyy = foreign key,
// []T = has-many. Field pointers declare the rest.
type Author struct {
    storm.Model            // uuid id + created_at/updated_at
    Name     string
    Email    string
    Articles []Article
}

func (a *Author) Schema(t *storm.Table)           { t.Unique(&a.Email) }
func (a *Author) Plans(p *storm.Plans)            { p.Named("Feed").With(&a.Articles) }
func (a *Author) Projections(p *storm.Projections) { p.Named("Card", &a.Name, &a.Email) }

// Typed queries. A dynamic query has a bounded set of shapes; each compiles
// once, and a warm call allocates NOTHING to build its SQL.
rows, err := article.New().
    Where(article.AuthorID.Eq(id), article.PublishedAt.IsNotNull()).
    Order(article.PublishedAt.Desc()).
    All(ctx, ex, nil)

// The semi-join: authors who HAVE a published article. Child predicates are
// typed by the child's package; one EXISTS probe per row.
store.AuthorHavingArticles(author.New(), article.PublishedAt.IsNotNull())

// The named plan: authors WITH their articles — exactly two round trips
// whatever the row count, and reading an unloaded relation DOES NOT COMPILE.
feed, err := store.AuthorFeed().Limit(10).All(ctx, ex)

// Writes are masked: unset columns take their database defaults, and an
// UPDATE writes only what was assigned. A version column makes stale writers
// lose loudly. Graph writes flush in FK order, one batch, atomic.
n := author.Create(); n.SetName("Ada"); n.SetEmail("ada@example.com")
ada, err := n.Insert(ctx, ex)

// Declared aggregations: GROUP BY without dropping to SQL. The result types
// are PostgreSQL's, not the input's — count is int64, sum(numeric) is a
// NULLABLE Decimal, because over zero rows it IS null.
func (o *Order) Aggregates(a *storm.Aggregates) {
    a.Named("ByStatus").By(&o.Status).Count("Orders").Sum(&o.Total, "Revenue")
}
rows, err := order.New().Where(order.PlacedAt.Gte(t)).AllByStatus(ctx, ex)

// Joins project ACROSS tables, declared with field pointers into a local var.
// LEFT is in the type: anything from the right side is Null[T].
func (o *Order) Joins(j *storm.Joins) {
    var c Customer
    j.Named("WithCustomer").Inner(&c, &o.Customer).
        Take(&o.ID, "OrderID").Take(&c.Email, "Email").OrderDesc(&o.PlacedAt)
}
rows, err := order.New().Where(order.Status.Eq("paid")).AllWithCustomer(ctx, ex)

// Anything PostgreSQL can run, typed, validated against the model at
// generate time — mismatches fail the build naming the column and the fix.
var Top = storm.SQL[TopRow](`WITH ranked AS (...) SELECT ... LIMIT $1`)
var Purge = storm.SQLExec(`DELETE FROM sessions WHERE expires_at < now()`)

The numbers

Measured, never quoted from memory — the methodology and every caveat live in bench/RESULTS.md. At 1,000 rows, allocations per query:

storm raw pgx sqlc Bun Ent GORM
6 5,012 5,022 13,899 23,016 23,934

Measured on Go 1.26.6. The allocation counts above were re-checked on 1.27 and are unchanged — they are what this table is about. The wall-clock figures have not been, and one offline benchmark did move; the note at the top of bench/RESULTS.md has the detail.

Wall clock is round-trip-dominated for every ORM — the honest claims are allocations, GC pressure (storm 21 GCs vs pgx's 102 on the 2M-row workload), and the plans: Exists() is a LIMIT 1 probe, relation loads carry no useless ORDER BY, per-parent limits lower to LATERAL (measured 33× over row_number() at 100 parents), and projections make index-only scans possible.

Tooling

Install it, run it, write no bootstrap. There is no registry to maintain and no main to keep in step with your models — storm finds them by parsing (ADR-0006):

go install github.com/gsoultan/storm/cmd/storm@latest
go get github.com/gsoultan/storm/tool     # once per module

storm generate [dir]    # one package per table + the context package
      watch <dir>       # regenerate on save; leave it running while you edit
      models            # what discovery found, and which rule matched
      diff <name>       # a reviewable migration; never applied by storm
      verify            # drift: model vs database
      verify -stale     # generated code vs model (no database, unless you declare storm.SQL)
      verify -pending   # model vs migrations — "forgot to diff" fails CI
      lint              # every named plan costed in round trips, budgeted
      explain           # every statement planned; large seq scans flagged
      import            # an existing database, written back as a model draft
      portable <engine> # what in this model does NOT cross to another engine

A type is a model when it embeds storm.Model, or declares a Schema, Plans or Projections method, or carries //storm:model; //storm:ignore opts out. A type embedded in another struct is a mixin, not a table. storm models prints the verdict and the rule behind it.

Field pointers still resolve at runtime — storm writes the bootstrap it used to ask you for, runs it, and removes it. The hand-written tool.Main(model.All(), model.Queries()) is still supported and generates byte-identical code (EXAMPLE §2).

You do not have to remember to regenerate. The step cannot be removed — Go has no build hook — but two things remove the remembering. storm watch keeps the tree current as you save. And generated code carries a shape assertion, so a model that gained, lost, renamed or reordered a field stops the build naming that field, instead of silently missing it:

store/shape.gen.go:57:2: too few values in struct literal of type model.Product

Changes inside Schema, Plans or Projections are method bodies the type system cannot see; storm verify -stale is still the check for those.

A worked service

examples/orders is a Go kit microservice on storm, in its own module: catalogue, checkout that reserves stock under concurrency, order retrieval, and a finance report. Its concurrency test puts 12 goroutines against a stock of 20 and asserts nothing is oversold.

$ cd examples/orders && storm generate store && go test ./orders/

Design documents

CONCEPT · ARCHITECTURE · DIALECTS · COMPARISON · PLAN — the ADRs, including the rejected-ideas list, are under docs/adr. Some API sketches in the design docs describe planned surface (joins with cross-table rows, aggregate projections); the example and the generated code are the as-built truth.

Scheduling without a race

During storm.TstzRange                       // in the model
t.Exclude(storm.With(&b.Room, storm.OpEq),
          storm.With(&b.During, storm.OpOverlaps))

booking.New().Where(booking.During.Overlaps(window)).All(ctx, ex, nil)

Half-open by default, so [09:00, 11:00) and [11:00, 12:00) abut rather than clash. The overlap is enforced by a GiST exclusion constraint — two concurrent bookings for one room cannot both commit — and the loser gets runtime.ErrExclusionViolation. No other Go ORM models exclusion constraints, and they are the correct answer to booking, scheduling and rate-plan overlap.

Full-text search

Search storm.TSVector          // in the model
t.Col(&p.Search).Generated(storm.Expr(`to_tsvector('english', name)`)).Index()

product.New().Where(product.Search.WebSearch(q)).All(ctx, ex, nil)

Filterable, never readable: a tsvector is index support, so it is absent from Row and from writes. The term is bound, so a search for '); DROP TABLE -- is a search for those words. Optional filters compose without a nil check: q = product.WhenSet(q, f.MinPrice, product.Price.Gte).

Errors you can switch on

Constraint violations are typed at the driver boundary, so a handler never decodes a SQLSTATE:

_, err := n.Insert(ctx, ex)
switch {
case errors.Is(err, runtime.ErrUniqueViolation):     // 409, and ce.Constraint says which
case errors.Is(err, runtime.ErrForeignKeyViolation): // 400
case runtime.Retryable(err):                          // 40001/40P01 — run it again
}

ConstraintError names the constraint, table and column and carries no bound value; PostgreSQL's own diagnostic does, and it stays reachable through Unwrap. Anything storm has no opinion about comes back unchanged.

Boundaries

No applied DDL. No lazy loading — ever; unloaded relations do not compile. No runtime dialect branch. No reflection under runtime/. Every "no" is a year of maintenance not spent; the reasoning lives in the ADRs.

Documentation

Overview

Package storm is the public surface: the types you declare a model with, and the builder that turns those models into a schema.

Index

Constants

View Source 
const (
	OpEq       = "="
	OpOverlaps = "&&"
	OpAdjacent = "-|-"
)

Exclusion operators.

View Source 
const (
	BTree = "btree"
	GIN   = "gin"
	GiST  = "gist"
	Hash  = "hash"
	BRIN  = "brin"
)

Index methods.

View Source 
const MaxTimeOfDay = runtime.MaxTimeOfDay

MaxTimeOfDay is 24:00:00, which PostgreSQL accepts as a `time`.

Variables

This section is empty.

Functions

func Build 

func Build(models ...any) (*schema.Schema, error)

Build turns a set of model structs into a schema. Pass pointers to zero values: Build(&User{}, &Org{}, &Post{}).

Every declaration problem is collected and reported together, because failing on the first one would mean N build cycles to find N mistakes.

func DeclOf 

func DeclOf(d RawDecl) (reflect.Type, string)

DeclOf reads a registered query's row type and SQL; the generate command uses it and nothing else should.

func RegisterScanner 

func RegisterScanner[T any](fn func([][]byte, *T, *runtime.Slab) error)

RegisterScanner is called by generated code from an init(). One scanner per row type: two queries sharing a row type share its scanner, which is safe because the generator validated both against the same descriptor shape.

Types

type Action 

type Action string

Action is a referential action for OnDelete/OnUpdate. 

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

type AggregateBuilder added in v0.3.0 

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

AggregateBuilder accumulates one declaration.

func (*AggregateBuilder) Avg added in v0.3.0 

func (b *AggregateBuilder) Avg(x any, as string) *AggregateBuilder

func (*AggregateBuilder) By added in v0.3.0 

func (b *AggregateBuilder) By(fieldPtrs ...any) *AggregateBuilder

By groups by columns. The field name is derived from the column name.

func (*AggregateBuilder) ByExpr added in v0.3.0 

func (b *AggregateBuilder) ByExpr(as string, t Term) *AggregateBuilder

ByExpr groups by an expression, which needs a name because date_trunc('day', placed_at) has no obvious one.

func (*AggregateBuilder) Count added in v0.3.0 

func (b *AggregateBuilder) Count(as string) *AggregateBuilder

Count adds count(*): rows per group, never NULL.

func (*AggregateBuilder) CountOf added in v0.3.0 

func (b *AggregateBuilder) CountOf(fieldPtr any, as string) *AggregateBuilder

CountOf adds count(col), which counts rows where the column is NOT NULL — a different question from Count, and a common bug, so a different method.

func (*AggregateBuilder) Cube added in v0.3.0 

func (b *AggregateBuilder) Cube() *AggregateBuilder

Cube is ROLLUP's every-combination sibling: 2ⁿ grouping sets.

func (*AggregateBuilder) DenseRank added in v0.3.0 

func (b *AggregateBuilder) DenseRank(as string, w *WindowSpec) *AggregateBuilder

func (*AggregateBuilder) Filter added in v0.3.0 

func (b *AggregateBuilder) Filter(c Cond) *AggregateBuilder

Filter restricts the LAST aggregate to the rows matching cond — `count(*) FILTER (WHERE status = 'paid')`, which is both clearer and faster than `count(CASE WHEN ...)`.

func (*AggregateBuilder) FirstValue added in v0.3.0 

func (b *AggregateBuilder) FirstValue(x any, as string, w *WindowSpec) *AggregateBuilder

FirstValue is the first row's value in the window.

func (*AggregateBuilder) GroupingOf added in v0.3.0 

func (b *AggregateBuilder) GroupingOf(as string, fieldPtrs ...any) *AggregateBuilder

GroupingOf adds GROUPING(cols...) — 1 when the row is a subtotal over those columns, 0 when the value is real.

func (*AggregateBuilder) Having added in v0.3.0 

func (b *AggregateBuilder) Having(c Cond) *AggregateBuilder

Having filters the GROUPS, after aggregation. A call-site Where filters the rows that go INTO the groups; these are different questions and mixing them up silently changes the answer.

func (*AggregateBuilder) Lag added in v0.3.0 

func (b *AggregateBuilder) Lag(x any, as string, w *WindowSpec) *AggregateBuilder

Lag and Lead read the previous or next row in the window. Both are NULL at the partition edge however non-null the column is, so both produce a nullable field.

func (*AggregateBuilder) Lead added in v0.3.0 

func (b *AggregateBuilder) Lead(x any, as string, w *WindowSpec) *AggregateBuilder

func (*AggregateBuilder) Max added in v0.3.0 

func (b *AggregateBuilder) Max(x any, as string) *AggregateBuilder

func (*AggregateBuilder) Min added in v0.3.0 

func (b *AggregateBuilder) Min(x any, as string) *AggregateBuilder

func (*AggregateBuilder) OverWindow added in v0.3.0 

func (b *AggregateBuilder) OverWindow(w *WindowSpec) *AggregateBuilder

OverWindow attaches a window to the LAST aggregate — a moving total, or the classic "share of the group" without a self-join.

func (*AggregateBuilder) Rank added in v0.3.0 

func (b *AggregateBuilder) Rank(as string, w *WindowSpec) *AggregateBuilder

func (*AggregateBuilder) Rollup added in v0.3.0 

func (b *AggregateBuilder) Rollup() *AggregateBuilder

Rollup turns the grouping into ROLLUP(...): every prefix of the grouping columns plus a grand total, in one pass instead of one query per level.

Every grouping column becomes NULLABLE in the row type, because a subtotal row carries NULL for the columns it aggregated over. Use storm.Grouping to tell that NULL from one that was in the data.

func (*AggregateBuilder) RowNumber added in v0.3.0 

func (b *AggregateBuilder) RowNumber(as string, w *WindowSpec) *AggregateBuilder

RowNumber, Rank and DenseRank number rows within the window.

func (*AggregateBuilder) Sets added in v0.3.0 

func (b *AggregateBuilder) Sets(sets ...[]string) *AggregateBuilder

Sets declares explicit grouping sets by the names given to By/ByExpr. An empty set is the grand total row.

This is the answer to N+1 queries per facet: one pass over the table produces every facet count, instead of one query per facet.

func (*AggregateBuilder) Sum added in v0.3.0 

func (b *AggregateBuilder) Sum(x any, as string) *AggregateBuilder

Sum, Avg, Min and Max are the ordinary aggregates. All four are NULL over zero rows, so all four produce a nullable field.

type Aggregates added in v0.3.0 

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

Named aggregations: a GROUP BY and the expressions over it, declared once. 

func (o *Order) Aggregates(a *storm.Aggregates) {
    a.Named("Daily").
        ByExpr("Day", storm.DateTrunc("day", &o.PlacedAt)).
        Count("Orders").
        Count("Paid").Filter(storm.Eq(&o.Status, StatusPaid)).
        Sum(&o.Total, "Revenue").
        RowNumber("Rank", storm.Over().OrderByDesc(&o.Total))
}

rows, err := order.New().
    Where(order.PlacedAt.Gte(since)).   // call-site predicates still compose
    AllDaily(ctx, ex)                   // []order.DailyRow

**Declared, not composed at the call site**, for the reason the library exists: a `GroupBy(...).Select(...)` chain assembled at run time has an unbounded set of result shapes, and a shape storm has not seen can have neither a generated scanner nor a compiled statement. Naming it keeps the whole thing inside the compilation thesis. The call-site predicates stay dynamic because those ARE bounded.

func (*Aggregates) Named added in v0.3.0 

func (a *Aggregates) Named(name string) *AggregateBuilder

Named starts an aggregation. The generated type is this name plus "Row", so "Daily" becomes DailyRow in the table's package.

type Aggregator added in v0.3.0 

type Aggregator interface {
	Aggregates(*Aggregates)
}

Aggregator is implemented by models that declare aggregations. Optional.

type ColBuilder 

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

ColBuilder configures one column.

func (*ColBuilder) Cidr 

func (b *ColBuilder) Cidr() *ColBuilder

Cidr narrows a netip.Prefix column from inet to cidr — the database then rejects host bits, which is the entire difference between the two types.

func (*ColBuilder) Comment 

func (b *ColBuilder) Comment(s string) *ColBuilder

func (*ColBuilder) Date 

func (b *ColBuilder) Date() *ColBuilder

Date narrows a time.Time column to a calendar date. The Go type stays time.Time (there is no stdlib date), decoded as midnight UTC.

func (*ColBuilder) Default 

func (b *ColBuilder) Default(e Expr) *ColBuilder

func (*ColBuilder) Generated 

func (b *ColBuilder) Generated(e Expr) *ColBuilder

func (*ColBuilder) Immutable 

func (b *ColBuilder) Immutable() *ColBuilder

func (*ColBuilder) Index 

func (b *ColBuilder) Index() *ColBuilder

Index adds a single-column index.

func (*ColBuilder) Named 

func (b *ColBuilder) Named(n string) *ColBuilder

func (*ColBuilder) NotNull 

func (b *ColBuilder) NotNull() *ColBuilder

func (*ColBuilder) Nullable 

func (b *ColBuilder) Nullable() *ColBuilder

func (*ColBuilder) Numeric 

func (b *ColBuilder) Numeric(p, s int) *ColBuilder

func (*ColBuilder) OnDelete 

func (b *ColBuilder) OnDelete(a Action) *ColBuilder

OnDelete and OnUpdate set the referential action of this column's foreign key.

func (*ColBuilder) OnUpdate 

func (b *ColBuilder) OnUpdate(a Action) *ColBuilder

func (*ColBuilder) Raw 

func (b *ColBuilder) Raw(sqlType string) *ColBuilder

Raw forces a database type storm does not model.

func (*ColBuilder) Size 

func (b *ColBuilder) Size(n int) *ColBuilder

func (*ColBuilder) Unique 

func (b *ColBuilder) Unique() *ColBuilder

Unique adds a single-column unique constraint. On a foreign key this is what turns one-to-many into one-to-one.

func (*ColBuilder) Version 

func (b *ColBuilder) Version() *ColBuilder

type Cond added in v0.3.0 

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

Cond is a DECLARED predicate, used by FILTER and HAVING.

Distinct from a call-site Where, which is dynamic: that varies per call and is a token stream spliced into a cached statement with bound arguments. A FILTER or HAVING is part of the declaration and never varies, so it is rendered into the text.

func And added in v0.3.0 

func And(cs ...Cond) Cond

And, Or and Not compose conditions. Always parenthesised when rendered: AND/OR precedence is a classic source of silently wrong predicates and the brackets cost nothing.

func Eq added in v0.3.0 

func Eq(l, r any) Cond

Eq and friends compare a column (or expression) with a declared literal.

func Gt added in v0.3.0 

func Gt(l, r any) Cond

func Gte added in v0.3.0 

func Gte(l, r any) Cond

func IsNotNull added in v0.3.0 

func IsNotNull(x any) Cond

func IsNull added in v0.3.0 

func IsNull(x any) Cond

IsNull and IsNotNull test for NULL, which `= NULL` does not.

func Lt added in v0.3.0 

func Lt(l, r any) Cond

func Lte added in v0.3.0 

func Lte(l, r any) Cond

func Ne added in v0.3.0 

func Ne(l, r any) Cond

func Not added in v0.3.0 

func Not(c Cond) Cond

func Or added in v0.3.0 

func Or(cs ...Cond) Cond

type Decimal 

type Decimal = runtime.Decimal

Decimal is an exact fixed-point number for a numeric column.

An alias, not a wrapper: the model declares storm.Decimal and generated code reads runtime.Decimal, and those must be the same type or every value would need converting at the boundary storm exists to remove.

float64 is not offered for numeric. It cannot represent 0.10, and an accounting system that rounds is a defect rather than a tolerance — so the choice is made once, here, instead of by whoever writes the model.

func ParseDecimal 

func ParseDecimal(s string) (Decimal, error)

ParseDecimal reads a decimal from its text form.

type Enumer 

type Enumer interface {
	EnumValues() []string
}

Enumer marks a named type as a Postgres enum. Constants are not discoverable through reflection, so the type has to list them. 

type Status string
const (StatusActive Status = "active"; StatusBanned Status = "banned")
func (Status) EnumValues() []string { return []string{"active", "banned"} }

type ExcludeBuilder 

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

ExcludeBuilder configures an exclusion constraint.

func (*ExcludeBuilder) Named 

func (b *ExcludeBuilder) Named(n string) *ExcludeBuilder

func (*ExcludeBuilder) Using 

func (b *ExcludeBuilder) Using(method string) *ExcludeBuilder

func (*ExcludeBuilder) Where 

func (b *ExcludeBuilder) Where(e Expr) *ExcludeBuilder

type ExcludeSpec 

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

ExcludeSpec is one `<column-or-expression> WITH <operator>` part.

func With 

func With(field any, op string) ExcludeSpec

With pairs a field with an exclusion operator.

func WithExpr 

func WithExpr(e Expr, op string) ExcludeSpec

WithExpr pairs an expression with an exclusion operator, for the range overlap that scalar columns cannot express: 

t.Exclude(storm.With(&b.Room, storm.OpEq),
          storm.WithExpr("tstzrange(starts_at, ends_at)", storm.OpOverlaps))

type Expr 

type Expr string

Expr is a raw SQL fragment. It is the one deliberate escape from the typed API: conspicuous, reported by `storm lint --expr`, and validated against the database at generate time.

func GenRandomUUID 

func GenRandomUUID() Expr

GenRandomUUID renders gen_random_uuid(), built in since PostgreSQL 13. This is the default for an embedded storm.Model because it works everywhere the rest of storm does.

func Now 

func Now() Expr

Now renders the SQL now() default.

func UUIDv7 

func UUIDv7() Expr

UUIDv7 renders a uuidv7() default. Requires PostgreSQL 18+.

type IndexBuilder 

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

IndexBuilder configures an index after Index(...).

func (*IndexBuilder) Named 

func (b *IndexBuilder) Named(n string) *IndexBuilder

func (*IndexBuilder) Unique 

func (b *IndexBuilder) Unique() *IndexBuilder

func (*IndexBuilder) Using 

func (b *IndexBuilder) Using(method string) *IndexBuilder

func (*IndexBuilder) Where 

func (b *IndexBuilder) Where(e Expr) *IndexBuilder

type IndexColumn 

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

IndexColumn is a field reference with ordering or an expression applied.

func Asc 

func Asc(field any) IndexColumn

Asc is the default; provided for symmetry.

func Desc 

func Desc(field any) IndexColumn

Desc orders an index key descending.

func Lower 

func Lower(field any) IndexColumn

Lower indexes lower(col) — the usual answer for case-insensitive uniqueness.

func NullsLast 

func NullsLast(ic IndexColumn) IndexColumn

NullsLast puts NULLs at the end of an index key.

type Interval 

type Interval = runtime.Interval

Interval is a PostgreSQL interval: months, days and microseconds kept separate, because a month has no fixed length and a day is not always 24 hours. An alias for the same reason Decimal is — the model's type and the generated code's type must be one type.

type JoinBuilder added in v0.3.0 

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

JoinBuilder accumulates one declaration.

func (*JoinBuilder) Inner added in v0.3.0 

func (b *JoinBuilder) Inner(model any, on any) *JoinBuilder

Inner and Left attach a table.

`on` is either a relation field pointer on the declaring model — the FK says how to join, so there is nothing to spell — or an explicit condition built with storm.OnCols.

func (*JoinBuilder) InnerWith added in v0.3.0 

func (b *JoinBuilder) InnerWith(alias string, on JoinOn) *JoinBuilder

InnerWith and LeftWith attach a CTE that With() put in scope.

With() materialises it; these say how it joins. Two steps because a CTE can be referenced by more than one join condition, and because "declare it" and "attach it" are genuinely different decisions.

func (*JoinBuilder) Left added in v0.3.0 

func (b *JoinBuilder) Left(model any, on any) *JoinBuilder

Left keeps every row of the left side. Every column taken from the right becomes nullable in the generated row, which is what a LEFT JOIN means.

func (*JoinBuilder) LeftWith added in v0.3.0 

func (b *JoinBuilder) LeftWith(alias string, on JoinOn) *JoinBuilder

LeftWith keeps rows with no matching CTE row. Everything taken from the CTE becomes nullable, which is what a LEFT join means — and for an aggregate CTE it is usually the right choice, because a customer with no orders has no row in a GROUP BY over orders.

func (*JoinBuilder) OrderAsc added in v0.3.0 

func (b *JoinBuilder) OrderAsc(fieldPtr any) *JoinBuilder

OrderAsc and OrderDesc order the joined result.

A join has no natural order, and an unordered multi-table result shuffles between requests — the same reason an aggregation orders by its grouping.

func (*JoinBuilder) OrderDesc added in v0.3.0 

func (b *JoinBuilder) OrderDesc(fieldPtr any) *JoinBuilder

func (*JoinBuilder) Take added in v0.3.0 

func (b *JoinBuilder) Take(fieldPtr any, as string) *JoinBuilder

Take adds a column to the output. The field pointer may be into the declaring model or into any joined one.

func (*JoinBuilder) TakeFrom added in v0.3.0 

func (b *JoinBuilder) TakeFrom(alias, column, as string) *JoinBuilder

TakeFrom adds a column from an aliased scope — a CTE's aggregate output.

func (*JoinBuilder) Where added in v0.3.0 

func (b *JoinBuilder) Where(c Cond) *JoinBuilder

Where declares a predicate the caller cannot widen. Call-site predicates still compose and are ANDed with it.

func (*JoinBuilder) With added in v0.3.0 

func (b *JoinBuilder) With(alias string, model any, aggregate string) *JoinBuilder

With materialises a declared aggregation as a CTE. 

var o Order
j.Named("VsSpend").
    With("spend", &o, "ByCustomer").
    Inner(&c, storm.OnCols("spend", "customer_id", &c.ID))

One pass over the aggregated table, reused by the join, instead of a correlated subquery per row.

type JoinOn added in v0.3.0 

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

JoinOn is an explicit join condition.

func OnCols added in v0.3.0 

func OnCols(alias, column string, fieldPtr any) JoinOn

OnCols joins on a named column of an aliased scope — a CTE's output column, or a table's column — against a field of the model being attached.

type Joiner added in v0.3.0 

type Joiner interface {
	Joins(*Joins)
}

Joiner is implemented by models that declare joins. Optional.

type Joins added in v0.3.0 

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

Named joins: one read that projects across tables. 

func (o *Order) Joins(j *storm.Joins) {
    var c Customer
    j.Named("WithCustomer").
        Inner(&c, &o.Customer).            // the FK relation says how to join
        Take(&o.ID, "OrderID").
        Take(&o.Total, "Total").
        Take(&c.Email, "Email").
        OrderDesc(&o.PlacedAt)
}

rows, err := order.New().
    Where(order.PlacedAt.Gte(since)).      // call-site predicates still compose
    AllWithCustomer(ctx, ex)               // []order.WithCustomerRow

**A join projects; it does not load entities.** The output is a flat row of scalars, because a join answers a question and materialising two entity types to answer it is the round-tripping this exists to avoid. When you want the entities, that is a Plan — one query per relation, no fan-out.

The joined model is a LOCAL variable. Taking field pointers into it is what makes `&c.Email` a checked reference rather than a string, so a rename of Customer.Email is a compile error here too.

func (*Joins) Named added in v0.3.0 

func (j *Joins) Named(name string) *JoinBuilder

Named starts a join. The generated type is this name plus "Row".

type Model 

type Model struct {
	ID        UUID
	CreatedAt time.Time
	UpdatedAt time.Time
}

Model is the conventional embedded primary key and timestamps. Embedding it is optional — declare your own key if you want a natural one.

It carries its own Schema method, so embedding it is the whole declaration: the key gets a default and is immutable, and both timestamps default to now().

func (*Model) Schema 

func (m *Model) Schema(t *Table)

type Nested 

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

Nested names a relation on a table OTHER than the one declaring the plan — a post's comments, reached through a user's posts.

It exists because a field pointer needs an instance to point into, and the declaring model has no Post to hand. Into supplies one: the builder already allocated a zero value of every registered model, so the closure is called with that and the offset resolves against the right table.

func Into 

func Into[T any](pick func(*T) any, nested ...Nested) Nested

Into names a relation on T, for use inside With. 

p.Named("Feed").With(&u.Posts, storm.Into(func(p *Post) any { return &p.Comments }))

The type parameter is what says which table the field belongs to, so a pointer into the wrong model is a compile error rather than a mis-resolved offset.

type Null 

type Null[T any] struct {
	V     T
	Valid bool
}

Null is the allocation-free nullable. A `*T` in a model becomes a Null[T] in the generated row type: a pointer would cost one allocation per non-nil field per row, and rows are the hot path.

func None 

func None[T any]() Null[T]

func Some 

func Some[T any](v T) Null[T]

Some and None construct a Null[T].

func (Null[T]) Get 

func (n Null[T]) Get() (T, bool)

type OneOf2 

type OneOf2[A, B any] struct {
	// contains filtered or unexported fields
}

OneOf2 is an exclusive arc over two variants.

type OneOf3 

type OneOf3[A, B, C any] struct {
	// contains filtered or unexported fields
}

OneOf3 is an exclusive arc over three variants.

type OneOf4 

type OneOf4[A, B, C, D any] struct {
	// contains filtered or unexported fields
}

OneOf4 is an exclusive arc over four variants.

type OneOf5 

type OneOf5[A, B, C, D, E any] struct {
	// contains filtered or unexported fields
}

OneOf5 is an exclusive arc over five variants.

type OneOf6 

type OneOf6[A, B, C, D, E, F any] struct {
	// contains filtered or unexported fields
}

OneOf6 is an exclusive arc over six variants.

type OneOf7 

type OneOf7[A, B, C, D, E, F, G any] struct {
	// contains filtered or unexported fields
}

OneOf7 is an exclusive arc over seven variants.

type OneOf8 

type OneOf8[A, B, C, D, E, F, G, H any] struct {
	// contains filtered or unexported fields
}

OneOf8 is an exclusive arc over eight variants.

type PlanBuilder 

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

PlanBuilder collects the relations one plan loads.

func (*PlanBuilder) With 

func (b *PlanBuilder) With(relPtr any, nested ...Nested) *PlanBuilder

With adds a relation to the plan, addressed by field pointer. Anything passed after it is loaded THROUGH it and costs one more round trip each.

type Planner 

type Planner interface {
	Plans(*Plans)
}

Planner is implemented by models that declare fetch plans. Optional: a model with no Plans method gets the one-plan-per-relation tier, which is finite by construction and needs no declaration.

type Plans 

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

Named fetch plans.

A plan says which relations are loaded together, and the generator emits a distinct type per plan whose fields are exactly those relations. Reading an unloaded relation is then a compile error rather than an empty slice.

You name the plans. That is the whole answer to the projection-type explosion: generating a type per `With(...)` combination is 2ⁿ per entity, and the fix is not a cleverer generator but a shorter list — the one the developer actually uses.

It also makes `plans.go` the single reviewable file listing every load pattern in a system, which is a thing no other Go ORM has, and which a linter can cost in round trips. 

func (u *User) Plans(p *storm.Plans) {
    p.Named("Feed").With(&u.Posts).With(&u.Org)
}

Relations are named by FIELD POINTER, like everything else in the declaration API, so the editor enforces them and a rename follows.

func (*Plans) Named 

func (p *Plans) Named(name string) *PlanBuilder

Named starts a plan. The generated type is the model name plus this name, so "Feed" on User becomes UserFeed.

type Projections 

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

Named projections: read less than the whole row, by name. 

func (u *User) Projections(p *storm.Projections) {
    p.Named("Contact", &u.Email, &u.Name)
}

rows, err := user.New().Where(...).AllContact(ctx, ex)   // []user.ContactRow

The full-row read is the safe default and the expensive one: every column travels, TOAST'd values are fetched whether or not anyone looks, and an index-only scan is impossible by construction. A named projection is the declared, reviewable subset — same predicates, same ordering, same keyset machinery, narrower tuple, its own generated row type and scanner.

Named rather than a Select(cols...) builder for R3's reason: a type per combination is 2ⁿ per entity, and the fix is a shorter list — the one the code actually uses.

func (*Projections) Named 

func (p *Projections) Named(name string, fieldPtrs ...any)

Named declares one projection over the given column fields.

type Projector 

type Projector interface {
	Projections(*Projections)
}

Projector is implemented by models that declare projections. Optional.

type RawDecl 

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

RawDecl is implemented by every SQLQuery, so a bootstrap can register them as a plain []any the way it registers models.

type SQLQuery 

type SQLQuery[T any] struct {
	// contains filtered or unexported fields
}

The typed escape hatch (M5).

Anything PostgreSQL can run is expressible here — CTEs, windows, lateral joins — years before the native IR grows each construct. What storm adds is the part hand-rolled SQL always loses: the RESULT is typed, the scanner is generated, and the statement was validated against the model at GENERATE time, so a query whose columns drifted from its row type fails the build naming the column, not the 3am page. 

var TopEarners = storm.SQL[EarnerRow](`
    WITH ranked AS (...)
    SELECT ... WHERE tenant_id = $1 ... LIMIT $2`)

rows, err := TopEarners.Query(ctx, db, tid, 3)   // []EarnerRow

How the scanner arrives

`storm generate` PREPAREs the statement, matches the result descriptor against T's fields, and emits a scanner that registers itself by type in an init(). The first Query looks it up once and caches it in the value; the warm path is an atomic load. Running a query nothing generated for is an error naming the fix, not a reflective fallback — one reflection path becomes THE path.

func SQL 

func SQL[T any](sql string) *SQLQuery[T]

SQL declares a raw query returning rows of T.

func (*SQLQuery[T]) One 

func (q *SQLQuery[T]) One(ctx context.Context, ex runtime.Executor, args ...any) (T, bool, error)

One runs the statement and returns the first row, if any.

func (*SQLQuery[T]) Query 

func (q *SQLQuery[T]) Query(ctx context.Context, ex runtime.Executor, args ...any) ([]T, error)

Query runs the statement and scans every row.

Args are variadic and checked against the statement's placeholder count before anything reaches the server; the ROW is where the typing lives, which is the half hand-rolled SQL cannot have.

type SQLStmt 

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

SQLStmt is the no-rows half of the escape hatch: DELETEs, junction-table INSERTs, `SELECT maintenance_fn(...)` calls. It carries no row type — and the generator enforces that, failing generation if the statement's result descriptor has columns, so "I meant to read those rows" cannot compile into silently dropping them.

func SQLExec 

func SQLExec(sql string) *SQLStmt

SQLExec declares a raw statement executed for its effect.

func (*SQLStmt) Exec 

func (q *SQLStmt) Exec(ctx context.Context, ex runtime.Executor, args ...any) (int64, error)

Exec runs the statement and reports rows affected.

type Schemer 

type Schemer interface {
	Schema(t *Table)
}

Schemer is implemented by models that need more than their Go types can say.

The receiver MUST be a pointer. With a value receiver Go copies the struct before the method runs, so &u.Email points into the copy and cannot be resolved back to a field — the builder rejects that at Build time rather than producing a silently wrong schema.

type TSVector added in v0.3.0 

type TSVector struct{}

TSVector is a full-text search column.

Declare one and PostgreSQL gets a `tsvector`; the generated query API gets Matches and WebSearch on it. It is deliberately an EMPTY struct: a tsvector is index support, not data, so it never appears in a Row, never travels on a read, and cannot be written from Go. The usual declaration makes the database maintain it: 

Search storm.TSVector

t.Col(&p.Search).
    Generated(storm.Expr(`to_tsvector('english', coalesce(name,''))`)).
    Index()

Nothing else in storm has this shape, and that is the point: a column you can only ask questions of.

type Table 

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

Table is the builder handed to a model's Schema method. Every reference to a field is a *field pointer* (&u.Email), so a rename is a compile error and a typo never compiles.

func (*Table) Check 

func (t *Table) Check(e Expr) *Table

Check adds a CHECK constraint.

func (*Table) Col 

func (t *Table) Col(fieldPtr any) *ColBuilder

Col addresses a column by field pointer and returns a builder for it. 

t.Col(&u.Email).Unique().Size(320)

func (*Table) Comment 

func (t *Table) Comment(s string) *Table

Comment sets a table comment.

func (*Table) Exclude 

func (t *Table) Exclude(parts ...ExcludeSpec) *ExcludeBuilder

Exclude adds an exclusion constraint — the correct answer to booking and scheduling overlap, and reachable from no other Go ORM. 

t.Exclude(storm.With(&b.Room, storm.OpEq), storm.With(&b.Period, storm.OpOverlaps))

func (*Table) Index 

func (t *Table) Index(cols ...any) *IndexBuilder

Index adds a secondary index. Wrap a field in Desc(...) or Lower(...) to order or transform it.

func (*Table) Name 

func (t *Table) Name(n string) *Table

Name overrides the table name inferred from the Go type.

func (*Table) PrimaryKey 

func (t *Table) PrimaryKey(fields ...any) *Table

PrimaryKey overrides the inferred key. Pass several field pointers for a composite key.

func (*Table) Unique 

func (t *Table) Unique(cols ...any) *Table

Unique adds a table-level uniqueness constraint.

Postgres UNIQUE constraints cannot contain expressions, so a Unique over one (Lower(&u.Email)) is emitted as a UNIQUE INDEX instead. Same guarantee, different object — and the alternative is DDL that does not parse.

type Term added in v0.3.0 

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

Term is an expression inside a declared aggregation: a column, a literal, a scalar function, or an aggregate over those.

It is not `Expr`, which is already the raw text of a CHECK constraint, and it is not the runtime predicate type either. A Term is resolved and TYPED at generation time — that is the whole point, because the generated row's field type is whatever the Term turns out to be.

Field pointers are accepted anywhere a Term is, so the common case reads as itself: storm.DateTrunc("day", &o.PlacedAt).

func Abs added in v0.3.0 

func Abs(x any) Term

Abs is the absolute value.

func Coalesce added in v0.3.0 

func Coalesce(args ...any) Term

Coalesce returns the first non-null argument.

func Col added in v0.3.0 

func Col(fieldPtr any) Term

Col is an explicit column reference. Rarely needed: a field pointer is accepted directly wherever a Term is.

func DateTrunc added in v0.3.0 

func DateTrunc(unit string, ts any) Term

DateTrunc buckets a timestamp — the reason grouping takes an expression at all. `unit` is a PostgreSQL field name: "hour", "day", "month", "year".

func Grouping added in v0.3.0 

func Grouping(fieldPtrs ...any) Term

Grouping reports, per row, whether a grouping set aggregated over these columns. It is how a ROLLUP's subtotal NULL is told apart from a NULL that was in the data — without it a subtotal row and a real NULL group are indistinguishable, which is a wrong answer that looks like a right one.

func Lit added in v0.3.0 

func Lit(v any) Term

Lit is a declaration-time constant.

Rendered into the statement rather than bound, because it comes from the declaration and never varies — which is what keeps a filtered aggregate one cached statement instead of one per value.

func NullIf added in v0.3.0 

func NullIf(a, b any) Term

NullIf returns NULL when the two arguments are equal — the division-by-zero guard, written where the division is rather than in a comment above it.

func Out added in v0.3.0 

func Out(name string) Term

Out references an output this aggregation already declared, by name. It is how Having talks about an aggregate: 

Count("Orders").
Having(storm.Gt(storm.Out("Orders"), 10))

PostgreSQL cannot see a SELECT alias in HAVING — aliases are resolved after grouping — so this expands to `count(*) > 10`, which is what it means.

func Star added in v0.3.0 

func Star() Term

Star is `*`, valid ONLY as the argument of Count. Anywhere else it is refused at declaration time: `HAVING * > 0` is not a query.

type TimeOfDay 

type TimeOfDay = runtime.TimeOfDay

TimeOfDay is a PostgreSQL `time` — microseconds since midnight, no date and no zone. See runtime.TimeOfDay for why it is not a time.Time.

func NewTimeOfDay 

func NewTimeOfDay(hour, min, sec, micro int) (TimeOfDay, bool)

NewTimeOfDay builds a time of day from its parts, reporting false for parts out of range rather than normalising them — 25:00 is a mistake, not 01:00 tomorrow.

type TstzRange added in v0.3.0 

type TstzRange = runtime.TstzRange

TstzRange is a PostgreSQL tstzrange: an interval of time with explicit bounds, so "do these two bookings overlap" is a question the database answers with an index rather than four comparisons in Go that get the boundary cases wrong.

An alias, not a wrapper, for the same reason Decimal is: the model declares storm.TstzRange and generated code reads runtime.TstzRange, and those must be the same type or every value would need converting at the boundary storm exists to remove.

func NewTstzRange added in v0.3.0 

func NewTstzRange(lower, upper time.Time) TstzRange

NewTstzRange builds the half-open range [lower, upper) — the one scheduling wants, because adjacent slots then do not collide on the instant they touch.

type UUID 

type UUID [16]byte

UUID keeps the core dependency-free. Map it to your preferred package once with a codec rather than importing one here.

func (UUID) String 

func (u UUID) String() string

type WindowSpec added in v0.3.0 

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

WindowSpec is an OVER clause under construction.

func Over added in v0.3.0 

func Over() *WindowSpec

Over starts a window.

func (*WindowSpec) OrderByAsc added in v0.3.0 

func (w *WindowSpec) OrderByAsc(xs ...any) *WindowSpec

OrderByAsc and OrderByDesc order rows WITHIN the partition.

Named this way rather than taking storm.Asc/storm.Desc because those already mean index ordering, and one word meaning two things in one declaration is how a wrong index gets built.

func (*WindowSpec) OrderByDesc added in v0.3.0 

func (w *WindowSpec) OrderByDesc(xs ...any) *WindowSpec

func (*WindowSpec) PartitionBy added in v0.3.0 

func (w *WindowSpec) PartitionBy(xs ...any) *WindowSpec

PartitionBy restarts the window for each distinct value.

Source Files

View all Source files

Directories

Path Synopsis
bench
entbench
entbench/enttest
entbench/hook
entbench/migrate
entbench/predicate
entbench/runtime
entbench/schema
Package schema is the Ent declaration for the shared bench table.
 Package schema is the Ent declaration for the shared bench table.
entbench/user
genuser
sqlcbench/gen
cmd
genbench command
genspike command
Command genspike generates the two table packages the M3 plan-type spike sits on top of.
 Command genspike generates the two table packages the M3 plan-type spike sits on top of.
storm command
Command storm is the tool: install it once, run it in your module, write no bootstrap.
 Command storm is the tool: install it once, run it in your module, write no bootstrap.
Package codegen emits Go from the schema IR.
 Package codegen emits Go from the schema IR.
compile
myddl
Package myddl renders a schema as MySQL 8 DDL.
 Package myddl renders a schema as MySQL 8 DDL.
pgddl
Package pgddl lowers the schema IR to PostgreSQL DDL.
 Package pgddl lowers the schema IR to PostgreSQL DDL.
pgsql
Package pgsql lowers query structure to PostgreSQL text.
 Package pgsql lowers query structure to PostgreSQL text.
examples
blog/gen command
Command gen regenerates the example's store from its model.
 Command gen regenerates the example's store from its model.
blog/model
Package model is the quickstart's schema: two tables, one relation, and the declared plans and projections this example reads with.
 Package model is the quickstart's schema: two tables, one relation, and the declared plans and projections this example reads with.
blog/store
blog/store/article
blog/store/author
internal
aliasrow
Package aliasrowx deliberately declares a name that differs from its directory (aliasrow).
 Package aliasrowx deliberately declares a name that differs from its directory (aliasrow).
benchmodel
Package benchmodel is the M0 benchmark table, declared as a model so the generator can be measured against the hand-written spike on identical SQL.
 Package benchmodel is the M0 benchmark table, declared as a model so the generator can be measured against the hand-written spike on identical SQL.
planspike/store
planspike/store/attachment
planspike/store/comment
planspike/store/event
planspike/store/org
planspike/store/post
planspike/store/user
spike
testmodel
Package testmodel is the fixture domain used by M1's round-trip tests.
 Package testmodel is the fixture domain used by M1's round-trip tests.
Package migrate diffs two schemas and emits a reviewable migration.
 Package migrate diffs two schemas and emits a reviewable migration.
Package runtime is what generated code calls at query time.
 Package runtime is what generated code calls at query time.
mydec
Package mydec decodes MySQL's binary result protocol.
 Package mydec decodes MySQL's binary result protocol.
pgxdrv
Package pgxdrv is the only package in storm that knows pgx exists.
 Package pgxdrv is the only package in storm that knows pgx exists.
Package schema is storm's schema IR: the single representation every front end produces and every back end consumes.
 Package schema is storm's schema IR: the single representation every front end produces and every back end consumes.
pg
Package pg reads a live PostgreSQL database into storm's schema IR.
 Package pg reads a live PostgreSQL database into storm's schema IR.
Package tool is the developer-facing command set — render DDL, diff a migration, generate packages, and verify that model, generated code, migrations and the live database all still agree — as a LIBRARY.
 Package tool is the developer-facing command set — render DDL, diff a migration, generate packages, and verify that model, generated code, migrations and the live database all still agree — as a LIBRARY.
bootstrap
Package toolbootstrap writes and runs the bootstrap main that adopters used to keep in their own repositories.
 Package toolbootstrap writes and runs the bootstrap main that adopters used to keep in their own repositories.
discover
Package tooldiscover finds an adopter's models in their source, so the tool does not have to be handed them.
 Package tooldiscover finds an adopter's models in their source, so the tool does not have to be handed them.

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.