An :iter query generates a method returning an iter.Seq over the query's rows, plus a function returning the query's error once the loop is done. This saves memory, especially for :many queries returning lots of rows; it also reduces latency because it allows the code to start processing earlier.
Usage looks like this:
authors, ferr := q.ListAuthors(ctx)
for author := range authors {
// ...
}
if err := ferr(); err != nil {
// ...
}There is some discussion about the best syntax for iterations (e.g. Close() functions) in #720. I've used this approach in production for a while now, and it feels very comfortable to me. Due to the ferr return, the compiler will warn us when we forget to check the error.
In order to keep this PR reviewable, it contains only the codegen changes, the PostgreSQL example and the documentation update. Further tests are in #4647.
For future reference, some of my considerations while designing this.
I decided for iter.Seq[T], func() error instead of iter.Seq2[T, error] mainly because the second is incompatible with adapters like slices.Collect. Also, this way, the loop doesn't need to check for an error every time, and it's harder to forget to check the error because the argument would be unused in that case.
Initially, I wanted to start the query eagerly when the function was called, so that the yield loop only scans the next row. It felt slightly more elegant to me, and also, it starts the query ever-so-slightly earlier than within the yield closure. However, the main downside that made me change my mind, is that that method causes the query to leak if user never ranges over the iterator. This can happen due to panics, early returns, context cancellations, etc. Smaller downsides is that that method reserves q until the range-over is done (which I don't mind very much), and that I didn't like the generated code much.
Because the query starts within the loop, it would be trivial to allow ranging over the objects twice, where the second range just runs the query again. While that feels natural for a SELECT loop, I decided not to allow this, because an INSERT ... RETURNING, UPDATE ... RETURNING or DELETE ... RETURNING would also be executed twice in that case. And this might not be obvious: chaining the sequence with e.g. slices.Collect(seq) would also trigger this. I lean towards defensive code, and so I decided to make the second range return an explicit error; intentionally repeating the query only costs one extra line of code, after all.