Entity states

Every entity a context knows about has a state. Usually ant manages that for you, and these calls are for the times you need to say it yourself.

The states

State	Means	Next 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.
ant.Detachedconst Detached = track.DetachedDetached entities are not tracked.	Not tracked	Nothing
ant.Addedconst Added = track.AddedAdded entities are inserted by the next SaveChanges.	New	INSERT
ant.Unchangedconst Unchanged = track.UnchangedUnchanged entities match what was loaded.	Matches what was loaded	Nothing
ant.Modifiedconst Modified = track.ModifiedModified entities are updated by the next SaveChanges.	Differs from what was loaded	UPDATE
ant.Deletedconst Deleted = track.DeletedDeleted entities are removed by the next SaveChanges.	Marked for removal	DELETE

Changing state

err := ant.Add(db, newUser)            // insert on the next save
err = ant.Remove(db, user)             // delete on the next save
err = ant.Attach(db, existing)         // track as it is, assumed saved
err = ant.MarkModified(db, disconnect) // write every field on the next save
ant.Detach(db, user)                   // stop tracking, forget changes
db.ClearTracked()                      // forget everything

MarkModified suits a struct from outside, such as a request body, whose earlier values are unknown.

Looking inside

ant.Entryfunc Entry[T any](h Handle, entity *T) *EntityEntry[T]Entry returns the tracking state of an entity. tells you what the tracker knows.

entry := ant.Entry(db, user)

fmt.Println(entry.State())   // Modified
fmt.Println(entry.Changed()) // [Age]

dirty := ant.IsDirty(entry, &U.Age)
before, err := ant.Original(entry, &U.Age)

ant.Tracked[User](db)func Tracked[T any](h Handle) []*TTracked returns the tracked entities of type T, oldest first. lists tracked entities, oldest first, and db.DebugTracked()func (c *Context) DebugTracked() stringDebugTracked describes every tracked entity, for logs and debugging. prints the tracker as text.

Saving a graph from outside

ant.TrackGraphfunc TrackGraph[T any](h Handle, root *T, decide func(GraphNode) State) errorTrackGraph walks a graph that came from outside, such as a request body, and tracks each entity in the state decide returns for it. saves a tree that came from outside, like a request body. Nothing says what it held before, so your function decides each entity's state.

err := ant.TrackGraph(db, incoming, func(n ant.GraphNode) ant.State {
	if n.HasKey {
		return ant.Modified
	}

	return ant.Added
})

err = db.SaveChanges(ctx)

Foreign keys are filled in as it walks. Returning ant.Detached skips an entity and everything below it.

See it tested: tests/features/change_tracking/states_test.go