From 8c508b8416376607e878e8d40fd36be7fa923e91 Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Thu, 18 Apr 2019 13:19:59 -0700 Subject: [PATCH] Documentation cleanup --- src/next/jdbc.clj | 34 ++++++++++++++++++--------- src/next/jdbc/sql.clj | 44 +++++++++++++++++------------------ src/next/jdbc/transaction.clj | 6 ++--- 3 files changed, 48 insertions(+), 36 deletions(-) diff --git a/src/next/jdbc.clj b/src/next/jdbc.clj index 4a0ceec..37be758 100644 --- a/src/next/jdbc.clj +++ b/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. - - If it is called on a PreparedStatement, it cannot produce a datafiable - result (because that requires a connectable instead)." + produce a Connection via a DataSource." ([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)) diff --git a/src/next/jdbc/sql.clj b/src/next/jdbc/sql.clj index d89826c..3cef56d 100644 --- a/src/next/jdbc/sql.clj +++ b/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}) - ;=> ["SELECT * FROM `user` WHERE `id` = ?" 9] - (for-query :user {:id nil} {:table-fn mysql :column-fn mysql}) - ;=> ["SELECT * FROM `user` WHERE `id` IS NULL"] - (for-query :user ["id = ? and opt is null" 9] {:table-fn mysql :column-fn mysql}) - ;=> ["SELECT * FROM `user` WHERE id = ? and opt is null" 9] - (for-delete :user {:opt nil :id 9} {:table-fn mysql :column-fn mysql}) - ;=> ["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}) - ;=> ["DELETE FROM `user` WHERE id = ? and opt is null" 9] - (for-update :user {:status 42} {} {:table-fn mysql :column-fn mysql}) - ;=> ["UPDATE `user` SET `status` = ? WHERE " 42] - (for-update :user {:status 42} {:id 9} {:table-fn mysql :column-fn mysql}) - ;=> ["UPDATE `user` SET `status` = ? WHERE `id` = ?" 42 9] - (for-update :user {:status 42, :opt nil} ["id = ?" 9] {:table-fn mysql :column-fn mysql}) - ;=> ["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}) - ;=> ["INSERT INTO `user` (`id`, `status`, `opt`) VALUES (?, ?, ?)" 9 42 nil] + (for-query :user {:id 9} {:table-fn sql-server :column-fn mysql}) + ;=> ["SELECT * FROM [user] WHERE `id` = ?" 9] + (for-query :user {:id nil} {:table-fn sql-server :column-fn mysql}) + ;=> ["SELECT * FROM [user] WHERE `id` IS NULL"] + (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] + (for-delete :user {:opt nil :id 9} {:table-fn sql-server :column-fn mysql}) + ;=> ["DELETE FROM [user] WHERE `opt` IS NULL AND `id` = ?" 9] + (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] + (for-update :user {:status 42} {} {:table-fn sql-server :column-fn mysql}) + ;=> ["UPDATE [user] SET `status` = ? WHERE " 42] + (for-update :user {:status 42} {:id 9} {:table-fn sql-server :column-fn mysql}) + ;=> ["UPDATE [user] SET `status` = ? WHERE `id` = ?" 42 9] + (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] + (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] (for-insert-multi :user [:id :status] [[42 "hello"] [35 "world"] [64 "dollars"]] - {:table-fn mysql :column-fn mysql})) - ;=> ["INSERT INTO `user` (`id`, `status`) VALUES (?, ?), (?, ?), (?, ?)" 42 "hello" 35 "world" 64 "dollars"]) + {:table-fn sql-server :column-fn mysql})) + ;=> ["INSERT INTO [user] (`id`, `status`) VALUES (?, ?), (?, ?), (?, ?)" 42 "hello" 35 "world" 64 "dollars"]) diff --git a/src/next/jdbc/transaction.clj b/src/next/jdbc/transaction.clj index 22dc2c4..2e40e2e 100644 --- a/src/next/jdbc/transaction.clj +++ b/src/next/jdbc/transaction.clj @@ -23,9 +23,9 @@ as read-only and/or rollback-only (so it will automatically rollback instead of committing any changes)." [^Connection con f opts] - (let [isolation (:isolation opts) - read-only (:read-only opts) - rollback-only (:rollback-only opts) + (let [isolation (:isolation opts) + read-only (:read-only opts) + rollback-only (:rollback-only opts) old-autocommit (.getAutoCommit con) old-isolation (.getTransactionIsolation con) old-readonly (.isReadOnly con)]