Fixes #116 by documenting multiple result sets

CHANGELOG.md

@@ -2,11 +2,10 @@
 
 Only accretive/fixative changes will be made from now on.
 
-* WIP support multiple result sets.
-
 Changes made since the 1.0.478 release:
 * Address #125 by making the result of `plan` foldable (in the `clojure.core.reducers` sense).
 * Address #124 by extending `next.jdbc.sql.builder/for-query` to support `:top` (SQL Server), `:limit` / `:offset` (MySQL/PostgreSQL), `:offset` / `:fetch` (SQL Standard).
+* Address #116 by adding a `:multi-rs` option to `execute!` to retrieve multiple result sets, for example from stored procedure calls or T-SQL scripts.
 * Allow `:all` to be passed into `find-by-keys` instead of an example hash map or a where clause vector so all rows will be returned (expected to be used with `:offset` etc to support simple pagination of an entire table).
 * Add `:columns` option to `find-by-keys` (and `get-by-id`) to specify a subset of columns to be returned in each row. This can also specify an alias for the column and allows for computed expressions to be selected with an alias.
 

doc/all-the-options.md

@@ -59,6 +59,8 @@ Any function that might realize a row or a result set will accept:
 * `:label-fn` -- if `:builder-fn` is specified as one of `next.jdbc.result-set`'s `as-modified-*` builders, this option must be present and should specify a string-to-string transformation that will be applied to the column label for each returned column name.
 * `:qualifier-fn` -- if `:builder-fn` is specified as one of `next.jdbc.result-set`'s `as-modified-*` builders, this option should specify a string-to-string transformation that will be applied to the table name for each returned column name. It will be called with an empty string if the table name is not available. It can be omitted for the `as-unqualified-modified-*` variants.
 
+In addition, `execute!` accepts the `:multi-rs true` option to return multiple result sets -- as a vector of result sets.
+
 > Note: Subject to the caveats above about `:builder-fn`, that means that `plan`, `execute!`, `execute-one!`, and the "friendly" SQL functions will all accept these options for generating rows and result sets.
 
 ## Statements & Prepared Statements

doc/getting-started.md

@@ -93,6 +93,8 @@ Since we used `execute-one!`, we get just one row back (a hash map). This also s
 If the result set contains no rows, `execute-one!` returns `nil`.
 When no result is available, and `next.jdbc` returns a fake "result set" containing the "update count", `execute-one!` returns just a single hash map with the key `next.jdbc/update-count` and the number of rows updated.
 
+In the same way that you would use `execute-one!` if you only want one row or one update count, compared to `execute!` for multiple rows or a vector containing an update count, you can also ask `execute!` to return multiple result sets -- such as might be returned from a stored procedure call, or a T-SQL script (for SQL Server) -- instead of just one. If you pass the `:multi-rs true` option to `execute!`, you will get back a vector of results sets, instead of just one result set: a vector of zero or more vectors. The result may well be a mix of vectors containing realized rows and vectors containing update counts, reflecting the results from specific SQL operations in the stored procedure or script.
+
 > Note: In general, you should use `execute-one!` for DDL operations since you will only get back an update count. If you have a SQL statement that you know will only return an update count, `execute-one!` is the right choice. If you have a SQL statement that you know will only return a single row in the result set, you probably want to use `execute-one!`. If you use `execute-one!` for a SQL statement that would return multiple rows in a result set, even though you will only get the first row back (as a hash map), the full result set will still be retrieved from the database -- it does not limit the SQL in any way.
 
 ### Options & Result Set Builders

src/next/jdbc.clj

@@ -214,7 +214,10 @@
 (defn execute!
   "General SQL execution function.
 
-  Returns a fully-realized result set.
+  Returns a fully-realized result set. When `:multi-rs true` is provided, will
+  return multiple result sets, as a vector of result sets. Each result set is
+  a vector of hash maps, by default, but can be controlled by the `:builder-fn`
+  option.
 
   Can be called on a `PreparedStatement`, a `Connection`, or something that can
   produce a `Connection` via a `DataSource`."