Fixes #124 by supporting pagination

Support `:all` in `find-by-keys`. Document all these options. Update the 
specs.

CHANGELOG.md

@@ -4,6 +4,7 @@ Only accretive/fixative changes will be made from now on.
 
 Changes made since the 1.0.478 release:
 * Address #124 by extending `next.jdbc.sql.builder/for-query` to support `:top` (SQL Server), `:limit` / `:offset` (MySQL/PostgreSQL), `:offset` / `:fetch` (SQL Standard).
+* 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).
 
 ## Stable Builds
 

doc/all-the-options.md

@@ -34,11 +34,18 @@ If you need additional options set on a connection, you can either use Java inte
 
 ## Generating SQL
 
-The "friendly" SQL functions all accept the following options (in addition to all the options that `plan`, `execute!`, and `execute-one!` can accept):
+Except for `query` (which is simply an alias for `execute!`), all the "friendly" SQL functions accept the following options (in addition to all the options that `plan`, `execute!`, and `execute-one!` can accept):
 
 * `:table-fn` -- the quoting function to be used on the string that identifies the table name, if provided,
 * `:column-fn` -- the quoting function to be used on any string that identifies a column name, if provided.
 
+They also support a `:suffix` argument which can be used to specify a SQL string that should be appended to the generated SQL string before executing it, e.g., `:suffix "FOR UPDATE"`.
+
+In addition, `find-by-keys` accepts the following options (see its docstring for more details):
+
+* `:order-by` -- specify one or more columns, on which to sort the results,
+* `:top` / `:limit` / `:offset` / `:fetch` to support pagination of results.
+
 ## Generating Rows and Result Sets
 
 Any function that might realize a row or a result set will accept:

src/next/jdbc/specs.clj

@@ -138,6 +138,10 @@
         :args (s/cat :clazz #(instance? Class %)
                      :db-spec ::db-spec-or-jdbc))
 
+(s/fdef connection/component
+        :args (s/cat :clazz #(instance? Class %)
+                     :db-spec ::db-spec-or-jdbc))
+
 (s/fdef prepare/execute-batch!
         :args (s/cat :ps ::prepared-statement
                      :param-groups (s/coll-of ::params :kind sequential?)
@@ -174,7 +178,8 @@
         :args (s/cat :connectable ::connectable
                      :table keyword?
                      :key-map (s/or :example ::example-map
-                                    :where ::sql-params)
+                                    :where ::sql-params
+                                    :all #{:all})
                      :opts (s/? ::opts-map)))
 
 (s/fdef sql/get-by-id

src/next/jdbc/sql.clj

@@ -82,8 +82,8 @@
   columns and values to search on or a vector of a SQL where clause and
   parameters, returns a vector of hash maps of rows that match.
 
-  If the vector is empty -- no SQL and no parameters -- the query will
+  If `:all` is passed instead of a hash map or vector -- the query will
-  select all rows in the table: be warned!
+  select all rows in the table, subject to any pagination options below.
 
   If the `:order-by` option is present, add an `ORDER BY` clause. `:order-by`
   should be a vector of column names or pairs of column name / direction,

src/next/jdbc/sql/builder.clj

@@ -152,11 +152,13 @@
   `SELECT ...` statement."
   [table where-params opts]
   (let [entity-fn    (:table-fn opts identity)
-        where-params (if (map? where-params)
+        where-params (cond (map? where-params)
-                       (by-keys where-params :where opts)
+                           (by-keys where-params :where opts)
-                       (into [(when-let [clause (first where-params)]
+                           (= :all where-params)
-                                (str "WHERE " clause))]
+                           []
-                             (rest where-params)))
+                           :else
+                           (into [(str "WHERE " (first where-params))]
+                                 (rest where-params)))
         where-params (cond-> (if (:top opts)
                                (into [(first where-params)]
                                      (cons (:top opts) (rest where-params)))

test/next/jdbc/sql/builder_test.clj

@@ -45,15 +45,10 @@
             {:table-fn sql-server :column-fn mysql :order-by [:a [:b :desc]]})
            [(str "SELECT * FROM [user] WHERE id = ? and opt is null"
                  " ORDER BY `a`, `b` DESC") 9])))
-  (testing "with nil where clause"
+  (testing "by :all"
     (is (= (builder/for-query
             :user
-            nil
+            :all
-            {:table-fn sql-server :column-fn mysql :order-by [:a [:b :desc]]})
-           ["SELECT * FROM [user] ORDER BY `a`, `b` DESC"]))
-    (is (= (builder/for-query
-            :user
-            [nil]
             {:table-fn sql-server :column-fn mysql :order-by [:a [:b :desc]]})
            ["SELECT * FROM [user] ORDER BY `a`, `b` DESC"])))
   (testing "top N"