Fixes #35 by documenting the DB-specific insert multi options

CHANGELOG.md

@@ -6,7 +6,7 @@ Only accretive/fixative changes will be made from now on.
 
 The following changes have been committed to the **master** branch since the 1.0.0 release:
 
-* None.
+* Fix #35 by explaining the database-specific options needed to ensure `insert-multi!` performs a single, batched operation.
 
 ## Stable Builds
 

doc/friendly-sql-functions.md

@@ -50,6 +50,11 @@ Given a table name (as a keyword), a vector of column names, and a vector row va
                    "Aunt Sally" "sour@lagunitas.beer"] {:return-keys true})
 ```
 
+Note: some database drivers need to be told to rewrite the SQL for this to
+be performed as a single, batched operation. In particular, PostgreSQL
+requires the `:reWriteBatchedInserts true` option and MySQL requires
+`:rewriteBatchedStatement true` (both non-standard JDBC options, of course!).
+
 ## `query`
 
 Given a vector of SQL and parameters, execute it:

src/next/jdbc/sql.clj

@@ -190,7 +190,12 @@
   Given a connectable object, a table name, a sequence of column names, and
   a vector of rows of data (vectors of column values), inserts the data as
   multiple rows in the database and attempts to return a vector of maps of
-  generated keys."
+  generated keys.
+
+  Note: some database drivers need to be told to rewrite the SQL for this to
+  be performed as a single, batched operation. In particular, PostgreSQL
+  requires the `:reWriteBatchedInserts true` option and MySQL requires
+  `:rewriteBatchedStatement true` (both non-standard JDBC options, of course!)."
   ([connectable table cols rows]
    (insert-multi! connectable table cols rows {}))
   ([connectable table cols rows opts]