Concepts

Almost everything in ant comes back to five ideas. Once they click, the rest of the API reads like plain English.

Models are plain structs

There's no base type you have to embed, no generated code, and no schema file. A struct maps to a table, its fields map to columns, and the field names decide the column names. Most of the time, that's all the configuration you'll write.

type Book struct {
	ID    int64
	Title string
	Pages int
}

type LibraryDB struct {
	ant.Context
	Books ant.Table[Book]
}

A probe names a column

ant.Fields[T]()func Fields[T any]() *TFields returns a probe for T. A probe holds no data. gives you a *T that never holds any data. It's there so that &B.Pages is a pointer ant can recognise. The compiler sees a *int, so whatever you compare it with has to be an int.

var B = ant.Fields[Book]()

books, err := db.Books.
	Where(ant.Gt(&B.Pages, 100)).
	All(ctx)

There's more on this in field probes.

The context is your database

You declare a struct with an ant.Table[T]type Table[] struct{ … }Table is a typed entry point to one model. for each model, and ant.Openfunc Open[DB any]( ctx context.Context, d dialect.Dialect, dsn string, options ...Option, ) (*DB, error)Open connects to a database and returns a populated context. fills it in. Tables, transactions, and sessions all hand you back that same typed struct, so db.Users works the same everywhere.

type AppDB struct {
	ant.Context
	Users ant.Table[User]
	Posts ant.Table[Post]
}

db, err := ant.Open[AppDB](ctx, postgres.Dialect, dsn)

Errors arrive at the last call

Builder methods like Wherefunc (t *Table[T]) Where(c ...Cond) *Query[T]Where starts a query with conditions. and OrderByfunc (t *Table[T]) OrderBy[V Ordered](field *V) *Query[T]OrderBy starts a query ordered by field, ascending. never return an error, which keeps chains readable. Mistakes are collected along the way, and the call that actually runs the query hands them back. That call always takes a context.Context first.

query := db.Users.
	Where(ant.Gt(&U.Age, 18)).
	OrderBy(&U.Name)

users, err := query.All(ctx) // runs here, and fails here

Allfunc (t *Table[T]) All(ctx context.Context) ([]*T, error)All returns every row., Firstfunc (t *Table[T]) First(ctx context.Context) (*T, error)First returns the first row, or ErrNotFound., Singlefunc (t *Table[T]) Single(ctx context.Context) (*T, error)Single returns the only row., Findfunc (t *Table[T]) Find[K comparable](ctx context.Context, key K) (*T, error)Find returns the entity with the given primary key, or ErrNotFound., Count, Exists, Eachfunc (t *Table[T]) Each(ctx context.Context) iter.Seq2[T, error]Each streams every row., Insertfunc (t *Table[T]) Insert(ctx context.Context, entities ...*T) errorInsert writes entities and the new entities related to them, parents first, in one transaction, so either all are saved or none are., Updatefunc (q *Query[T]) Update(ctx context.Context, a ...Assignment) (int64, error)Update applies assignments to every matching row and returns the number of rows changed., Deletefunc (q *Query[T]) Delete(ctx context.Context) (int64, error)Delete removes every matching row and returns the number removed., Exec, and SaveChangesfunc (c *Context) SaveChanges(ctx context.Context) errorSaveChanges writes every change to tracked entities in one transaction: inserts and updates with parents first, then deletes with children first. are the calls that run something. Everything before them just describes the query.

Nothing happens behind your back

Reading a field never runs a query. A relation you didn't load stays nil, and one you loaded that has no rows is an empty slice, so you can always tell the two apart. Loading is something you ask for, and it's always batched.

user, err := db.Users.Find(ctx, id)

fmt.Println(user.Posts == nil) // true: not loaded, and no query ran

user, err = db.Users.Include(&U.Posts).Find(ctx, id)

fmt.Println(user.Posts == nil) // false: loaded, even if there are none

Writing is just as explicit: nothing is saved until you call SaveChanges.

What the compiler cannot catch

Generics catch a lot, but not everything. These mistakes compile, and ant reports them when the query runs. antvet catches them before you run anything at all.

Mistake	Example	Error
A probe from the wrong model	db.Posts.Where(ant.Gt(&U.Age, 18))	ant.ErrWrongModelvar ErrWrongModel = errors.New("ant: field belongs to a model outside this query")ErrWrongModel reports a probe from a model the query does not use.
A pointer that isn't a probe	ant.Gt(&age, 18)func Gt[V Ordered](field *V, v V) CondGt matches rows where field is greater than v.	ant.ErrNotProbevar ErrNotProbe = errors.New("ant: pointer is not a field of a probe from ant.Fields")ErrNotProbe reports a field pointer that does not come from Fields.
A key of the wrong type	db.Users.Find(ctx, "1")	ant.ErrKeyTypevar ErrKeyType = errors.New("ant: key type does not match the primary key")ErrKeyType reports a key whose type does not match the primary key.