Database callbacks
Code that runs around every statement, registered in one place and wired onto every connection. Field encryption, HTML sanitising and the append-only guard already work this way; internal/dbchain is how yours joins them.
Why a registry rather than db.Callback()
GORM lets you register a callback on a *gorm.DB whenever you like, and nothing stops you doing that. Three things go wrong when you do.
- It lands on one connection. The handle you happened to hold, not the one the test suite opens, or the desktop app's local mirror, or the one a worker made. The application then behaves differently from its own tests, and nothing says why.
- Its order is whatever it is. A callback registered before
crypto:encrypt_map_valuessees plaintext; one after it sees ciphertext. Both compile. - Nothing can tell you what is on the chain, which is the first question when one of them turns out to be slow.
Registering a link
func init() {dbchain.MustRegister(dbchain.Link{Name: "myapp:stamp_region",Op: dbchain.Create,When: dbchain.After,Anchor: "fieldtypes:create",Why: "fills region from the actor's organization",Fn: stampRegion,})}func stampRegion(tx *gorm.DB) {// tx.Statement.Context carries the request, the actor and the// organization, the same way it does inside a service.}
Register touches no connection. dbchain.Apply(db) does that, and database.Connect already calls it, so a link registered from an init is on every handle opened afterwards. Call Apply yourself anywhere else you open one.
Ordering
When and Anchor are the ordering, together: run before or after a named callback. One constraint, not a list, because that is all GORM has.Anchor left empty means the statement itself, which is what you want unless your link has to see a value another one writes.
After("nope") without complaint and gives you no ordering at all, which is a callback running in the wrong place and saying nothing about it. Apply checks every anchor before it registers anything, so a typo leaves the connection as it was and tells you.The anchors you can name: GORM's own, and this framework's.
gorm:create gorm:query gorm:update gorm:delete gorm:row gorm:rawgorm:before_create gorm:after_create gorm:preload ...crypto:encrypt_map_values sanitize:html_create sanitize:html_updatefieldtypes:create fieldtypes:updateappendonly:update appendonly:deletepaginate:count_create paginate:count_updatepaginate:count_delete paginate:count_rawsync:soft_delete_touches_updated_at
Recording the queries a run makes
Set GRIT_QUERY_LOG and the chain writes one JSON line per query: the request that issued it, the matched route, the SQL with its placeholders, the row count, and the line of your application it came from. No code change, and nothing is recorded when the variable is unset.
GRIT_QUERY_LOG=.grit/queries.jsonl go test ./...# or run the app and use itGRIT_QUERY_LOG=.grit/queries.jsonl go run ./cmd/server
{"at":"2026-11-13T12:29:03Z","request":"1794572943-6149904","route":"GET /api/v1/posts","op":"query","table":"users","sql":"SELECT * FROM `users` WHERE id = ?","rows":1,"caller":"internal/services/post.go:88"}
The SQL keeps its placeholders. The shape is what a repeated query has in common, and the values are both the part that differs and the part that would put an email address in a file somebody pastes into an issue.
Reading it back
grit doctor reads the file and reports the same query issued many times inside one request, which is what an N+1 looks like from the outside.
grit doctorgrit doctor --queries ci-run.jsonl # somewhere else
⚠ GET /api/v1/posts runs the same query 23 times in one request,from internal/services/post.go:88 (in 14 requests):SELECT * FROM `users` WHERE id = ?load them in one query instead: Preload the relation, or fetch the idsand use a single IN (...).(query-repeated-in-one-request)
It is silent when there is no log. It also says so when the log is older than the code, because a report from before a change reads exactly the same as one from after it, and that is the whole danger of an artefact on disk.
grit doctor reads in CI, with nothing running. Use Pulse to see a slow request; use this to fail a build.The inventory
dbchain.Links() is the chain, sorted, so printing it twice gives the same answer and a diff of it means something.
GRIT_QUERY_LOG unset in production.