I have endeavoured to document this in style similar to the other query/statement mangling functions.
This functionality can be quite valuable, allowing the database to handle a great many book-keeping items.
Support multi-row INSERT/UPDATE with RETURNING.
Includes documentation, too.
Sorry about prior request; should not have asked to merge in from master.
Oh, no problem, though I will copy my response to the other request:
You can simply the implementation of returning to returning = query. ;-)
returning = query
Though this question/issue does come up on a semi-regular basis, and actually it was Carl Howells that first pointed out to me that postgresql-simple already supports returning clauses, after I was fretting over this same issue. So at the very least, documentation needs to be improved, though perhaps there is a case for adding a separate "returning" operator.
Hmm, my apologies, I'm not correct in my assessment, am I?
This returning supports multiple input rows; I do not believe query does.
Yeah, you are right.