add @frozar as documentation contributor

.all-contributorsrc

@@ -456,6 +456,15 @@
         "bug",
         "code"
       ]
+    },
+    {
+      "login": "frozar",
+      "name": "ROZAR Fabien",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/1025244?v=4",
+      "profile": "https://www.linkedin.com/in/fabien-rozar-975a7a106/",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

article.md

@@ -0,0 +1,59 @@
+# Migrating from `clojure.java.jdbc`
+
+This page attempts to list all of the differences between [clojure.java.jdbc](https://github.com/clojure/java.jdbc) and `next.jdbc`. Some of them are large and obvious, some of them are small and subtle -- all of them are deliberate design choices.
+
+## Conceptually
+
+`clojure.java.jdbc` focuses heavily on a `db-spec` hash map to describe the various ways of interacting with the database and grew from very imperative origins that expose a lot of the JDBC API (multiple types of SQL execution, some operations returned hash maps, others update counts as integers, etc).
+
+`next.jdbc` focuses on using protocols and native Java JDBC types where possible (for performance and simplicity) and strives to present a more modern Clojure API with namespace-qualified keywords in hash maps, reducible SQL operations as part of the primary API, and a streamlined set of SQL execution primitives. Execution always returns a hash map (for one result) or a vector of hash maps (for multiple results) -- even update counts are returned as if they were result sets.
+
+### Rows and Result Sets
+
+`clojure.java.jdbc` returned result sets (and generated keys) as hash maps with simple, lower-case keys by default. `next.jdbc` returns result sets (and generated keys) as hash maps with qualified, as-is keys by default: each key is qualified by the name of table from which it is drawn, if known. The as-is default is chosen to a) improve performance and b) not mess with the data. Using a `:builder-fn` option of `next.jdbc.result-set/as-unqualified-maps` will produce simple, as-is keys. Using a `:builder-fn` option of `next.jdbc.result-set/as-unqualified-lower-maps` will produce simple, lower-case keys -- the most compatible with `clojure.java.jdbc`'s default behavior.
+
+If you used `:as-arrays? true`, you will need to use a `:builder-fn` option of `next.jdbc.result-set/as-arrays` (or the unqualified or lower variant, as appropriate).
+
+## Primary API
+
+`next.jdbc` has a deliberately narrow primary API that has (almost) no direct overlap with `clojure.java.jdbc`:
+
+* `get-datasource` -- has no equivalent in `clojure.java.jdbc` but is intended to emphasize `javax.sql.DataSource` as a starting point,
+* `get-connection` -- overlaps with `clojure.java.jdbc` (and returns a `java.sql.Connection`) but accepts only a subset of the options (`:dbtype`/`:dbname` hash map, `String` JDBC URI); `clojure.java.jdbc/get-connection` accepts `{:datasource ds}` whereas `next.jdbc/get-connection` accepts the `javax.sql.DataSource` object directly,
+* `prepare` -- somewhat similar to `clojure.java.jdbc/prepare-statement` but it accepts a vector of SQL and parameters (compared to just a raw SQL string),
+* `reducible!` -- somewhat similar to `clojure.java.jdbc/reducible-query` but accepts arbitrary SQL statements for execution,
+* `execute!` -- has no direct equivalent in `clojure.java.jdbc` (but it can replace most uses of both `query` and `db-do-commands`),
+* `execute-one!` -- has no equivalent in `clojure.java.jdbc` (but it can replace most uses of `query` that currently use `:result-set-fn first`),
+* `transact` -- similar to `clojure.java.jdbc/db-transaction*`,
+* `with-transaction` -- similar to `clojure.java.jdbc/with-db-transaction`.
+
+If you were using a bare `db-spec` hash map with `:dbtype`/`:dbname`, or a JDBC URI string everywhere, that should mostly work with `next.jdbc` since most functions accept a "connectable", but it would be better to create a datasource first, and then pass that around.
+
+If you were already creating `db-spec` as a pooled connection datasource -- a `{:datasource ds}` hashmap -- then passing `(:datasource db-spec)` to the `next.jdbc` functions is the simplest migration path.
+
+If you were using other forms of the `db-spec` hash map, you'll need to adjust to one of the three modes above, since those are the only ones supported in `next.jdbc`.
+
+The `next.jdbc.sql` namespace contains several functions with similarities to `clojure.java.jdbc`'s core API:
+
+* `insert!` -- similar to `clojure.java.jdbc/insert!` but only supports inserting a single map,
+* `insert-multi!` -- similar to `clojure.java.jdbc/insert-multi!` but only supports inserting columns and a vector of row values,
+* `query` -- similar to `clojure.java.jdbc/query`,
+* `find-by-keys` -- similar to `clojure.java.jdbc/find-by-keys` but will also accept a partial where clause (vector) instead of a hash map of column name/value pairs,
+* `get-by-id` -- similar to `clojure.java.jdbc/get-by-id`,
+* `update!` -- similar to `clojure.java.jdbc/update!` but will also accept a hash map of column name/value pairs instead of a partial where clause (vector),
+* `delete!` -- similar to `clojure.java.jdbc/delete!` but will also accept a hash map of column name/value pairs instead of a partial where clause (vector).
+
+If you are using `:identifiers` and/or `:entities`, you will need to change to appropriate `:builder-fn` and/or `:table-fn`/`:column-fn` options. For the latter, instead of the `quoted` function, there is the `next.jdbc.quoted` namespace which contains functions for the common quoting strategies.
+
+If you are using `:result-set-fn` and/or `:row-fn`, you will need to change to explicit calls (to the result set function, or to `map` the row function), or to use the `reducible!` approach with `reduce` or various transducing functions. Note: this means that result sets are never exposed lazily in `next.jdbc` -- in `clojure.java.jdbc` you had to be careful that your `:result-set-fn` was eager, but in `next.jdbc` you either reduce the result set eagerly (via `reducible!`) or you get a fully-realized result set data structure back (from `execute!` and `execute-one!`). As with `clojure.java.jdbc` however, you can still stream result sets from the database and process them via reduction (was `reducible-query`, now `reducible!`). Remember that you can terminate a reduction early by using the `reduced` function to wrap the final value you produce.
+
+## Further Minor differences
+
+These are mostly drawn from [Issue #5](https://github.com/seancorfield/next-jdbc/issues/5) although most of the bullets in that issue are described in more detail above.
+
+* Keyword options no longer end in `?` -- to reflect the latest best practice on predicates vs. attributes,
+* `with-db-connection` has been replaced by just `with-open` containing a call to `get-connection`,
+* `with-transaction` can take a `:rollback-only` option, but there is no way to change a transaction to rollback _dynamically_; throw an exception instead (all transactions roll back on an exception)
+* The extension points for setting parameters and reading columns are now `SettableParameter` and `ReadableColumn` protocols.
+
+[<: `datafy`, `nav`, and `:schema`](/doc/datafy-nav-and-schema.md)

cljdoc-deploy

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEowIBAAKCAQEAq2yTRf6SYdU+kQe8iCb608vs0loGmIRPQ2Sf8axi/RZEKHsh
+Af8X29BNzsaHCV4dCm8W50tYKpLi9XLzU9Uukr9/hq2CmXSroEt2ppUJ2Aut2dGn
+9n0lQFYoTRRqLeP10pTOLCIt0Ae/4yzGxtvhYokvlKtUXgUnhCT08cb5SmiMzFA4
+0WkQX1d12HKet7+bgrlZZ7ZGyJPeQuABKwtcuECQkDIJTlLY631CjpKJU523oJCL
+U1P9aHmHzkuTxUKIKo1uzu+Rcba8ES9k84u1R3/99+Qtof2RfXdBR9QDYyo2jEyx
+Xm4NJ2vpASvx8YcfIrcbgN7eGVnhLn3Wg6oaawIDAQABAoIBAB22KOSF1htM2ZZL
+j/rNPsY83yQqZGBE9nQI2cwKg/G3zUJy7Oqqqxj3RrUjJb6S6Fepn3+hSHvAj8PZ
+E6GhHnxi4piWND+iwCh9S+hdhqJCi/Rn6UPItw8qn7uUYT7o9u9zyTRPDD+1SCX4
+2c8Xxz3L50pOU8YkAJBf03Cgew7RPYq1cjZ+nzevP4hChj0gp/HujB5DAN5oR1YD
+GmJyUWA8d1aG+Ce/DWfPKw56PvbQf9Hx8o08UDBnpqxy1KAV2cG4x1jWjIvYuqKq
+247pmIp+5GWtcDNUlMbbBu3XowM/we545MmQezhuqEy5FFO5otgnmhYM3mRJjGcy
+WKkfNSECgYEA1ndOPdIpomsbqW8jbVJ15gfjnpgf7on4mAaCjM/fQfjrau+eNEO+
+6vyjzf76Ofcnw5+gBLfDqblDfdB6HnBIai8HCZ8s+ZdQGuQXnryWOQDpIstpzte8
+BRDCnX5xQoCs3BehZpcc6HyF59G6EzdTerNUe3R5tRk8gfmWKQaCozECgYEAzJ9b
+s+qEbB8iSA++yTEGy1mmJw+z7t+4vHtegTwq9YantdfJY0Hm6G/ibZrbU18WUELM
+aPeWEHZadRYDBBWdPrGRgSnyqAainNzTqWrWCS0czA+cj9vXCQukcL4sCVJkWwOU
+1tZAyTxySDyNi2loHl20vswHqnkeR8YSnUBlmFsCgYEAgNvkTe7Fh0oVr8MQJTJj
+llftIrBCl1+c1zMqI5MOkKQQRws8IikGQEiV30KxdDyVTsvNKKiFTqf67lBh34IV
+cH9bGiPisQCCZ/XeX0judcefTIGtzFMBLIX6eQis4olP01n7Zxmqi+GtzzDLPZqD
+dPjk7Nx5+B72pR2iZHn96jECgYAQh3by66jSyxkL1SnGOs2fs5g2Y5BXZX8YyqZx
+rhiSSNRXXh0IhZRPhmo2DGJXM8ErrpmwiP94SPc5qhOISu6u1803L9pINHECVtxK
+PTUY/Kns2f39qPaP5n7cFKCeCCfPKlTlnd0R5G4e47VTY6pjeZJWL0kXPj1x8tAi
+H8eVLQKBgCxInxBQJxQCDb6jru5hnXs/i5ne6cY2/NcKQ0SVliFupH/WYqZo6hTp
+hXJQ5M1bwylBdrejvRbisA6bvDjytGCBmE/FwT/GNpFG1EKwei1Ui/q/2FQeYZYK
+KzdXBNjqeMNDiuyBiMsgVfd5RFwDyJJtBQbDZaCK6nRsSb47TpYu
+-----END RSA PRIVATE KEY-----

cljdoc-deploy.pub

@@ -0,0 +1 @@
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCrbJNF/pJh1T6RB7yIJvrTy+zSWgaYhE9DZJ/xrGL9FkQoeyEB/xfb0E3OxocJXh0KbxbnS1gqkuL1cvNT1S6Sv3+GrYKZdKugS3amlQnYC63Z0af2fSVAVihNFGot4/XSlM4sIi3QB7/jLMbG2+FiiS+Uq1ReBSeEJPTxxvlKaIzMUDjRaRBfV3XYcp63v5uCuVlntkbIk95C4AErC1y4QJCQMglOUtjrfUKOkolTnbegkItTU/1oeYfOS5PFQogqjW7O75FxtrwRL2Tzi7VHf/335C2h/ZF9d0FH1ANjKjaMTLFebg0na+kBK/Hxhx8itxuA3t4ZWeEufdaDqhpr martinklepsch@Martins-MacBook-Pro-2.local

doc/ideas/0001-inclusion-of-non-authoritative-documentation.md

@@ -0,0 +1,9 @@
+# Inclusion of Non-Authoritative Documentation
+
+During a discussion with Reid we realised that the inclusion of non-authoritative documentation might be quite feasible and have a positive impact on overall documentation.
+
+**Non-authoritative documentation** describes anything that is not authored or vetted by the maintainers of the project that is being documented. In the past this has been a common issue with `clojure.core`. Projects like ClojureDocs filled that gap by providing a platform where everyone can contribute documentation.
+
+For examples we could store them just like any other but add a flag `:not-authoritative?`. For docstrings this would work directly since there is only one doctsring per `def` or `ns` perhaps an extra field `:non-authoritative-doc` could contain a list of community provided docstrings.
+
+All keys subject to debate.

mini-config.edn

@@ -0,0 +1,12 @@
+{:secrets {}
+ :maven-repositories [{:id "lambdawerk-releases" :url "https://nexus.lambdawerk.com:8443/nexus/content/repositories/releases/"}
+                      {:id "lambdawerk-public" :url "https://nexus.lambdawerk.com:8443/nexus/content/repositories/public/"}]
+ :extension-namespaces [cljdoc.lambdawerk-xml]
+ :cljdoc/version #slurp "CLJDOC_VERSION"
+ :cljdoc/server {:port 8000
+                 :host "localhost"
+                 :analysis-service :local
+                 :disable-release-monitor? true
+                 :autobuild-clojars-releases? false
+                 :enable-sentry? false
+                 :dir "data-test/"}}

script/deploy.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -eou pipefail
+
+cd $(git rev-parse --show-toplevel)
+
+version=$(./script/version.sh)
+
+git tag $version
+
+pushd modules/deploy
+
+clj -m cljdoc.deploy deploy -t $version
+
+popd