Several statements in one round trip, each with its own result.

A BatchQuery pairs each statement with what to do with its results, and runBatchQuery sends them all in one request and reads the results in order:

(updated, Only total, items) <- runBatchQuery conn $ (,,)
  <$> batchExecute ("UPDATE item SET price = price * 1.1 WHERE category = " <> param cat)
  <*> batchQuery1 ("SELECT SUM(price) FROM item WHERE category = " <> param cat)
  <*> batchQuery ("SELECT id, name FROM item WHERE category = " <> param cat)
-- updated :: Int64, total :: Double, items :: [(Int32, Text)]

Each statement is its own sp_executesql call, all of them in one RPC message (as executeStatements sends them): the server compiles and runs them in order, and the response carries each one's results between its own DONEPROC markers, so a statement's consumer sees exactly its own result sets and counts, whatever the statements before it returned. A statement with no parameters is an sp_executesql call too, not a SQL batch, so a SET option it sets or a #temp table it creates lasts only until it returns; statements that must share such state go in one Query (its text joined, as Query is a Monoid) to queryResultSets instead. executeStatements conn qs is runBatchQuery conn (traverse batchExecute qs) with the counting done in bulk, and executeStatementsOutcomes the way to see which statements failed rather than the first that did.

The consumers mirror Hmssql.Query: batchExecute for execute, batchQuery for query (with batchQuery1, batchQueryMay, batchQueryFold, batchQueryS and the With variants), batchQueryMulti for queryMulti, batchQueryResultSets for queryResultSets. A statement's results are read as its consumer asks for them, and what it leaves unread is skipped before the next statement's, so a BatchQuery holds no more memory than its results; batchQueryS streams the last statement's rows after runBatchQuery returns, as queryS does.

Errors

The server runs the statements in order, and __statements after a failed one may have run__: an error that only ends its statement (a constraint violation, say) lets the server go on to the next; an error that aborts the batch (THROW, a conversion error, a deadlock, any error under SET XACT_ABORT ON) ends the request there. Outside a transaction each statement is committed as it completes. The first error is thrown as SqlServerError with its statement's text, once the whole response (and the messages after it, for a batch over about 1 MiB, as executeStatements explains) has been read, so the connection stays usable. For all-or-nothing, run the batch inside withTransaction and let the exception roll it back.

A statement that can't be sent (a value that can't be encoded, a placeholder with no parameter) throws EncodeError, naming its position, before its message is sent; so does a batchQueryS that isn't the last statement.

The shape is hpgsql's Hpgsql.Pipeline. It is called a batch because that is what TDS has: several statements in one request, run in order, each committed on its own, later ones running after an earlier one's error.

Only the last statement may stream. batchQueryS gives a stream to read after runBatchQuery returns, so a stream in the middle would leave the statements after it as actions you would have to run later, in order, on one thread. With only the last one streaming, there is no such order to get wrong.