Raw SQL

Raw SQL is a proper way out, not a hack. ant.Rawfunc Raw[T any](h Handle, query string, args ...any) *RawQuery[T]Raw prepares a raw SQL statement. runs your statement and scans the result into a model, any struct, or a single value.

Into a model

users, err := ant.Raw[User](db, `SELECT * FROM users WHERE age > ? ORDER BY name`, 18).All(ctx)

Allfunc (t *Table[T]) All(ctx context.Context) ([]*T, error)All returns every row. returns values, as []User, and Firstfunc (t *Table[T]) First(ctx context.Context) (*T, error)First returns the first row, or ErrNotFound. returns one row or ant.ErrNotFoundvar ErrNotFound = errors.New("ant: not found")ErrNotFound reports that a query for one row matched none.. Raw results aren't tracked.

Into any struct

Columns match fields by name. Columns with no field are ignored, and fields with no column stay zero.

type Summary struct {
	Name    string
	YearsOn int
}

rows, err := ant.Raw[Summary](db, `SELECT name, age + 1 AS years_on FROM users`).All(ctx)

ant.WithStrict makes a column with no field an error, which catches a model that has fallen behind its table.

Single values

count, err := ant.Raw[int](db, `SELECT count(*) FROM users`).First(ctx)
names, err := ant.Raw[string](db, `SELECT name FROM users ORDER BY name`).All(ctx)
now, err := ant.Raw[time.Time](db, `SELECT now()`).First(ctx)

NULL needs a nullable type: ant.Raw[sql.Null[string]].

Arguments

? works on every database and becomes the right placeholder for it. A slice fills IN (?), and named arguments work too. $1 still works on PostgreSQL, and so does the jsonb ? operator.

ages := []int{17, 30}

a, err := ant.Raw[User](db, `SELECT * FROM users WHERE age > ? AND name <> ?`, 18, "Alice").All(ctx)
b, err := ant.Raw[User](db, `SELECT * FROM users WHERE age IN (?)`, ages).All(ctx)
c, err := ant.Raw[User](db, `SELECT * FROM users WHERE age IN (@ages)`, sql.Named("ages", ages)).All(ctx)

An empty slice in IN (?) matches nothing, and so does an empty slice in NOT IN (?), which is what SQL itself says, and differs from ant.NotInfunc NotIn[V comparable](field *V, values ...V) CondNotIn matches rows where field equals none of values.. Outside IN, a slice is one array value, as in age = ANY($1).

Statements that return nothing

Exec returns the rows affected.

n, err := ant.Raw[any](db, `UPDATE users SET age = age + 1 WHERE age < ?`, 18).Exec(ctx)

SQL in a file

ant.RawFilefunc RawFile[T any](h Handle, fsys fs.FS, name string, args ...any) *RawQuery[T]RawFile is Raw with the statement read from a file in fsys, such as an embed.FS. loads a statement from any fs.FS, including go:embed. A missing file is reported at the terminal call.

//go:embed queries/*.sql
var queries embed.FS

func adults(ctx context.Context, db *AppDB) ([]User, error) {
	return ant.RawFile[User](db, queries, "queries/adults.sql", sql.Named("min", 18)).All(ctx)
}

Building on raw SQL

ant.FromRawfunc FromRaw[T any](h Handle, text string, args ...any) *Query[T]FromRaw returns a query over raw SQL, which conditions, ordering, and paging then build on. starts from your SQL and keeps going with typed methods. The SQL must return the model's columns.

adults := ant.FromRaw[User](db, `SELECT * FROM users WHERE age > ?`, 18)

page, err := adults.Where(ant.Lt(&U.Age, 35)).OrderBy(&U.Name).Limit(10).All(ctx)

For a fragment inside a typed query, use ant.SQL and ant.SQLCond.

Filters do not apply

ant.Raw runs your SQL as written, so global filters and soft deletes don't reach it. Never build the text from input: pass values as arguments.

See it tested: tests/features/querying/raw_test.go