Documentation cleanup

src/next/jdbc.clj

@@ -7,18 +7,33 @@
   * DataSource -- something to get connections from,
   * Connection -- an active connection to the database,
   * PreparedStatement -- SQL and parameters combined, from a connection,
-  and the following two functions and a macro:
+
+  and the following functions and a macro:
   * reducible! -- given a connectable and SQL + parameters or a statement,
       return a reducible that, when reduced will execute the SQL and consume
       the ResultSet produced,
   * execute! -- given a connectable and SQL + parameters or a statement,
       execute the SQL, consume the ResultSet produced, and return a vector
-      of hash maps representing the rows; this can be datafied to allow
+      of hash maps representing the rows (@1); this can be datafied to allow
       navigation of foreign keys into other tables (either by convention or
-      via a schema definition).
+      via a schema definition),
+  * execute-one! -- given a connectable and SQL + parameters or a statement,
+      execute the SQL, consume the first row of the ResultSet produced, and
+      return a hash map representing that row; this can be datafied to allow
+      navigation of foreign keys into other tables (either by convention or
+      via a schema definition),
+  * prepare -- given a Connection and SQL + parameters, construct a new
+      PreparedStatement; in general this should be used with `with-open`,
+  * transact -- the functional implementation of `with-transaction`,
   * with-transaction -- execute a series of SQL operations within a transaction.
 
-  The following options are supported where a PreparedStatement is created:
+  @1 result sets are built, by default, as vectors of hash maps, containing
+      qualified keywords as column names, but the row builder and result set
+      builder machinery is open and alternatives are provided to produce
+      unqualified keywords as column names, and to produce a vector the
+      column names followed by vectors of column values for each row.
+
+  The following options are supported wherever a PreparedStatement is created:
   * :concurrency -- :read-only, :updatable,
   * :cursors -- :close, :hold
   * :fetch-size -- the fetch size value,
@@ -128,10 +143,7 @@
   Invokes 'reducible!' and then reduces that into a vector of hash maps.
 
   Can be called on a PreparedStatement, a Connection, or something that can
-  produce a Connection via a DataSource.
+  produce a Connection via a DataSource."
-
-  If it is called on a PreparedStatement, it cannot produce a datafiable
-  result (because that requires a connectable instead)."
   ([stmt]
    (p/-execute-all stmt [] {}))
   ([connectable sql-params]
@@ -155,10 +167,10 @@
   "Given a connectable object and a function (taking a Connection),
   execute the function on a new connection in a transactional manner.
 
-  An options map may be provided before the function."
+  See `with-transaction` for supported options."
   ([connectable f]
    (p/-transact connectable f {}))
-  ([connectable opts f]
+  ([connectable f opts]
    (p/-transact connectable f opts)))
 
 (defmacro with-transaction
@@ -172,4 +184,4 @@
   * :read-only -- true / false,
   * :rollback-only -- true / false."
   [[sym connectable opts] & body]
-  `(transact ~connectable ~opts (fn [~sym] ~@body)))
+  `(transact ~connectable (fn [~sym] ~@body) ~opts))

src/next/jdbc/sql.clj

@@ -2,7 +2,7 @@
 
 (ns next.jdbc.sql
   "Some utility functions that make common operations easier by
-  providing some syntactic sugar over 'execute!'/'execute-one!'.
+  providing some syntactic sugar over `execute!`/`execute-one!`.
 
   This is intended to provide a minimal level of parity with clojure.java.jdbc
   (insert!, update!, delete!, etc). For anything more complex, use a library
@@ -221,34 +221,34 @@
    (execute-one! connectable (for-delete table where-params opts) opts)))
 
 (comment
-  (require '[next.jdbc.quoted :refer [mysql]])
+  (require '[next.jdbc.quoted :refer [mysql sql-server]])
   (by-keys {:a nil :b 42 :c "s"} :where {})
   ;=> ["WHERE a IS NULL AND b = ? AND c = ?" 42 "s"]
   (as-keys {:a nil :b 42 :c "s"} {})
   ;=> a, b, c
   (as-? {:a nil :b 42 :c "s"} {})
   ;=> ?, ?, ?
-  (for-query :user {:id 9} {:table-fn mysql :column-fn mysql})
+  (for-query :user {:id 9} {:table-fn sql-server :column-fn mysql})
-  ;=> ["SELECT * FROM `user` WHERE `id` = ?" 9]
+  ;=> ["SELECT * FROM [user] WHERE `id` = ?" 9]
-  (for-query :user {:id nil} {:table-fn mysql :column-fn mysql})
+  (for-query :user {:id nil} {:table-fn sql-server :column-fn mysql})
-  ;=> ["SELECT * FROM `user` WHERE `id` IS NULL"]
+  ;=> ["SELECT * FROM [user] WHERE `id` IS NULL"]
-  (for-query :user ["id = ? and opt is null" 9] {:table-fn mysql :column-fn mysql})
+  (for-query :user ["id = ? and opt is null" 9] {:table-fn sql-server :column-fn mysql})
-  ;=> ["SELECT * FROM `user` WHERE id = ? and opt is null" 9]
+  ;=> ["SELECT * FROM [user] WHERE id = ? and opt is null" 9]
-  (for-delete :user {:opt nil :id 9} {:table-fn mysql :column-fn mysql})
+  (for-delete :user {:opt nil :id 9} {:table-fn sql-server :column-fn mysql})
-  ;=> ["DELETE FROM `user` WHERE `opt` IS NULL AND `id` = ?" 9]
+  ;=> ["DELETE FROM [user] WHERE `opt` IS NULL AND `id` = ?" 9]
-  (for-delete :user ["id = ? and opt is null" 9] {:table-fn mysql :column-fn mysql})
+  (for-delete :user ["id = ? and opt is null" 9] {:table-fn sql-server :column-fn mysql})
-  ;=> ["DELETE FROM `user` WHERE id = ? and opt is null" 9]
+  ;=> ["DELETE FROM [user] WHERE id = ? and opt is null" 9]
-  (for-update :user {:status 42} {} {:table-fn mysql :column-fn mysql})
+  (for-update :user {:status 42} {} {:table-fn sql-server :column-fn mysql})
-  ;=> ["UPDATE `user` SET `status` = ? WHERE " 42]
+  ;=> ["UPDATE [user] SET `status` = ? WHERE " 42]
-  (for-update :user {:status 42} {:id 9} {:table-fn mysql :column-fn mysql})
+  (for-update :user {:status 42} {:id 9} {:table-fn sql-server :column-fn mysql})
-  ;=> ["UPDATE `user` SET `status` = ? WHERE `id` = ?" 42 9]
+  ;=> ["UPDATE [user] SET `status` = ? WHERE `id` = ?" 42 9]
-  (for-update :user {:status 42, :opt nil} ["id = ?" 9] {:table-fn mysql :column-fn mysql})
+  (for-update :user {:status 42, :opt nil} ["id = ?" 9] {:table-fn sql-server :column-fn mysql})
-  ;=> ["UPDATE `user` SET `status` = ?, `opt` = ? WHERE id = ?" 42 nil 9]
+  ;=> ["UPDATE [user] SET `status` = ?, `opt` = ? WHERE id = ?" 42 nil 9]
-  (for-insert :user {:id 9 :status 42 :opt nil} {:table-fn mysql :column-fn mysql})
+  (for-insert :user {:id 9 :status 42 :opt nil} {:table-fn sql-server :column-fn mysql})
-  ;=> ["INSERT INTO `user` (`id`, `status`, `opt`) VALUES (?, ?, ?)" 9 42 nil]
+  ;=> ["INSERT INTO [user] (`id`, `status`, `opt`) VALUES (?, ?, ?)" 9 42 nil]
   (for-insert-multi :user [:id :status]
                     [[42 "hello"]
                      [35 "world"]
                      [64 "dollars"]]
-                    {:table-fn mysql :column-fn mysql}))
+                    {:table-fn sql-server :column-fn mysql}))
-  ;=> ["INSERT INTO `user` (`id`, `status`) VALUES (?, ?), (?, ?), (?, ?)" 42 "hello" 35 "world" 64 "dollars"])
+  ;=> ["INSERT INTO [user] (`id`, `status`) VALUES (?, ?), (?, ?), (?, ?)" 42 "hello" 35 "world" 64 "dollars"])