Transactions

db.Txfunc (c *Context) Tx[DB any](ctx context.Context, f func(tx *DB) error, options ...TxOption) errorTx runs f in a transaction, passing a context of the same type bound to it. runs a function in a transaction. It commits if the function returns nil, and rolls back on an error or a panic. tx is your own context type, bound to that transaction.

Tx

err := db.Tx(ctx, func(tx *AppDB) error {
	bob := &User{Name: "Bob", Email: "bob@example.com"}

	if err := tx.Users.Insert(ctx, bob); err != nil {
		return err
	}

	return tx.Posts.Insert(ctx, &Post{UserID: bob.ID, Title: "First"})
})

The error comes back to you unchanged. Reads inside see the transaction's own writes, and a panic rolls back and then keeps panicking.

Use tx inside the function: anything you do on db runs outside the transaction. Cancelling the context rolls it back.

SaveChanges in a transaction

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. has its own implicit transaction, or joins the one it's in. If that transaction rolls back, the changes are pending again, and a rolled-back insert isn't tracked.

err := db.Tx(ctx, func(tx *AppDB) error {
	user, err := tx.Users.Find(ctx, id)
	if err != nil {
		return err
	}

	user.Age++

	return tx.SaveChanges(ctx)
})

ant.WithoutAutoTx()func WithoutAutoTx() OptionWithoutAutoTx stops SaveChanges and Insert from opening a transaction of their own, so a failure partway leaves earlier statements in place. stops SaveChanges and 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. from opening their own, so a failure partway leaves earlier statements in place. Use it only to control transactions yourself.

Nesting

A Tx inside a Tx becomes a savepoint, so only the inner part rolls back. That's also how you recover from a failed statement, which PostgreSQL otherwise won't let you do.

err := db.Tx(ctx, func(tx *AppDB) error {
	if err := tx.Users.Insert(ctx, alice); err != nil {
		return err
	}

	inner := tx.Tx(ctx, func(tx2 *AppDB) error {
		return tx2.Users.Insert(ctx, bob)
	})
	if inner != nil {
		log.Println("skipped bob:", inner)
	}

	return nil // alice commits either way
})

Begin

ant.Beginfunc Begin[DB any](ctx context.Context, db *DB, options ...TxOption) (*DB, error)Begin starts a transaction and returns a context bound to it. hands you the transaction to finish yourself. Prefer Tx where you can, since it can't leave one open by accident.

tx, err := ant.Begin(ctx, db)
if err != nil {
	return err
}

defer tx.Rollback()

if err := tx.Users.Insert(ctx, alice); err != nil {
	return err
}

return tx.Commit()

The second end is ant.ErrTxDonevar ErrTxDone = errors.New("ant: transaction has ended")ErrTxDone reports use of a transaction after it ended., which makes that deferred Rollbackfunc (c *Context) Rollback() errorRollback ends a transaction from Begin, discarding its changes. harmless. db.Commit()func (c *Context) Commit() errorCommit ends a transaction from Begin, keeping its changes. outside a transaction is ant.ErrNotInTxvar ErrNotInTx = errors.New("ant: not in a transaction")ErrNotInTx reports Commit, Rollback, or a savepoint outside a transaction..

Savepoints

err := tx.Savepoint(ctx, "before")
err = tx.RollbackTo(ctx, "before")
err = tx.Release(ctx, "before")

Isolation and read-only

Options go after the function, on Tx and Begin.

err := db.Tx(
	ctx,
	func(tx *AppDB) error {
		return nil
	},
	ant.Isolation(sql.LevelSerializable),
)

err = db.Tx(
	ctx,
	func(tx *AppDB) error {
		return nil
	},
	ant.ReadOnly(),
)

See it tested: tests/features/transactions/tx_test.go