GeezerVison

Problem

The :batchexec, :batchmany and :batchone sections of docs/reference/query-annotations.md list the batch object's methods but never explain them:

• what the func(int, error) callback actually receives, and what its int means
• what happens when one statement in the batch fails
• what Close does to statements that have not run yet ("close the batch operation early" is the only description)
• whether Close is needed at all when you iterate the whole batch

#4631 reports exactly this: a reader cannot tell what to do with the returned batch object from the docs alone.

Solution

Add a Using the batch object section documenting the callback contract and Close semantics, with a complete usage example and an early-abort example. Each of the three batch annotations now points at it with a same-page anchor link.

Documented behaviour:

• the callback is invoked once per queued statement, in order; the int is the statement's 0-based position in the batch, matching the slice index you passed in
• a failing statement does not stop iteration - if the third of ten statements fails, the callback still receives results for the fourth through tenth, so errors must be handled inside the callback
• Close before or during iteration skips the remaining statements, and their callbacks instead receive ErrBatchAlreadyClosed - once per remaining statement, so the callback always sees the full batch
• Close is called automatically when the iteration method returns (defer b.br.Close()), so a fully iterated batch needs no explicit Close

Everything stated is taken from the generated code itself - internal/codegen/golang/templates/pgx/batchCode.tmpl and the internal/endtoend/testdata/batch/postgresql/pgx/v5/go/batch.go golden file - not paraphrased from other documentation. I verified the callback and Close semantics by executing the generated loops against a pgx.BatchResults implementation (statements consumed in order, post-Close callbacks delivering ErrBatchAlreadyClosed, iteration continuing past statement errors).

Testing

The repo's docs content contract is enforced by internal/docs (added in #4584):

$ go test ./internal/docs/
ok  	github.com/sqlc-dev/sqlc/internal/docs	0.828s

Baseline before the edit: the same test passed, so the change introduces no new contract violations. All anchor links in the new section resolve under the linter's slugify rules, and the added content is plain CommonMark plus one GitHub alert (both allowed by the contract).

Not run: the full end-to-end suite requires live PostgreSQL/MySQL instances via Docker, which I don't have available; the documentation change does not touch code paths, and the docs test above is the gate that covers it.

Impact

Readers of the batch annotations can now use the returned batch object without reading sqlc's template source. The three existing sections keep their shape and gain one pointer line each.

Fixes #4631