Errors

Errors are values you can check. Builders collect them along the way, and the call that runs the query returns them, joined together if there's more than one.

Common errors

Match them with errors.Is, not by their text, which can change.

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

if errors.Is(err, ant.ErrNotFound) {
	return nil
}

Error	Means
ant.ErrNotFoundvar ErrNotFound = errors.New("ant: not found")ErrNotFound reports that a query for one row matched none.	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., or Reloadfunc (t *Table[T]) Reload(ctx context.Context, e *T) errorReload overwrites the columns of e with the stored row, found by e's primary key, or returns ErrNotFound. found no row
ant.ErrMultipleRowsvar ErrMultipleRows = errors.New("ant: query matched more than one row")ErrMultipleRows reports that Single matched more than one row.	Single found more than one
ant.ErrNoConditionvar ErrNoCondition = errors.New("ant: bulk write has no condition")ErrNoCondition reports a bulk write with no condition.	A bulk write with no condition
ant.ErrConcurrencyvar ErrConcurrency = errors.New("ant: row was changed or removed since it was loaded")ErrConcurrency reports that SaveChanges found a row changed or removed since it was loaded.	A version check failed
ant.ErrUnsupportedvar ErrUnsupported = errs.ErrUnsupportedErrUnsupported reports something the connected database cannot do, such as MERGE on MySQL.	This database lacks the feature
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 pointer that isn't a probe
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 probe of a model outside this query
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.	A key of the wrong type
ant.ErrNoKeyvar ErrNoKey = errors.New("ant: model has no primary key")ErrNoKey reports a key operation on a model with no primary key.	The model has no usable key for this
ant.ErrReadOnlyvar ErrReadOnly = errors.New("ant: model is read-only")ErrReadOnly reports a write to a read-only model, such as a view.	A write to a view
ant.ErrTxDonevar ErrTxDone = errors.New("ant: transaction has ended")ErrTxDone reports use of a transaction after it ended.	The transaction already ended

Database errors

These classify a database's error without string matching, on all five databases.

err := db.Users.Insert(ctx, user)

switch {
case ant.IsUniqueViolation(err):
	return errors.New("already exists")
case ant.IsForeignKeyViolation(err):
	return errors.New("refers to something missing")
case ant.IsNotNullViolation(err), ant.IsCheckViolation(err):
	return errors.New("invalid")
case ant.IsRetryable(err):
	return errors.New("try again")
}

ant.SQLState(err)func SQLState(err error) stringSQLState returns the database's error code for err, or "". returns the code itself, such as 23505, translated so one value means one thing everywhere.

Finding the statement

ant.FailedSQLfunc FailedSQL(err error) stringFailedSQL returns the statement behind a query error, or "". reads the statement behind a query error, with placeholders and no values, so it's safe for an internal log.

err := db.Users.Insert(ctx, user)

slog.Error("insert failed", "sql", ant.FailedSQL(err))

ant.WithDetailedErrors()func WithDetailedErrors() OptionWithDetailedErrors adds the failing statement to every query error's message, which helps in development. adds it to every error's message, which helps in development. Leave it off where errors reach users.

Strict scanning

By default a result column with no field is ignored. ant.WithStrict()func WithStrict() OptionWithStrict makes a query fail if a result column has no field, which usually means a model has fallen behind the schema, or a SELECT * picked up something new. refuses it, which catches a model that has fallen behind its table.

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

ant.WithLooseScan()func WithLooseScan() OptionWithLooseScan ignores result columns with no field. says the default out loud, where WithStrict is on for other contexts.

See it tested: tests/features/developer_tooling/errors_test.go