From b5048cca854ba15bd26f0a17975b24de79671c8a Mon Sep 17 00:00:00 2001 From: Sean Corfield Date: Fri, 8 Nov 2019 10:20:28 -0800 Subject: [PATCH] Improve migration docs `next.jdbc.connection` namespace docstring now mentions `dbtypes` and `->pool`. **Primary API** in the migration doc now explicitly recommends using a datasource for piecemeal migration. --- doc/migration-from-clojure-java-jdbc.md | 2 +- src/next/jdbc/connection.clj | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/migration-from-clojure-java-jdbc.md b/doc/migration-from-clojure-java-jdbc.md index b06664b..0565bb1 100644 --- a/doc/migration-from-clojure-java-jdbc.md +++ b/doc/migration-from-clojure-java-jdbc.md @@ -39,7 +39,7 @@ In particular, this means that you can't globally override the default options ( 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. Note that `clojure.java.jdbc` allowed the `jdbc:` prefix in a JDBC URI to be omitted but `next.jdbc` _requires that prefix!_ -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 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 are migrating piecemeal and want to support _both_ `clojure.java.jdbc` _and_ `next.jdbc` at the same time in your code, you should consider using a datasource as the common way to work with both libraries. You can using `next.jdbc`'s `get-datasource` or the `->pool` function (in `next.jdbc.connection`) to create the a `javax.sql.DataSource` and then build a `db-spec` hash map with it (`{:datasource ds}`) and pass that around your program. `clojure.java.jdbc` calls can use that as-is, `next.jdbc` calls can use `(:datasource db-spec)`, so you don't have to adjust any of your call chains (assuming you're passing `db-spec` around) and you can migrate one function at a time. 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`. diff --git a/src/next/jdbc/connection.clj b/src/next/jdbc/connection.clj index a7820c0..c3e21ca 100644 --- a/src/next/jdbc/connection.clj +++ b/src/next/jdbc/connection.clj @@ -1,7 +1,10 @@ ;; copyright (c) 2018-2019 Sean Corfield, all rights reserved (ns next.jdbc.connection - "Standard implementations of `get-datasource` and `get-connection`." + "Standard implementations of `get-datasource` and `get-connection`. + + Also provides `dbtypes` as a map of all known database types, and + the `->pool` function for creating pooled datasource objects." (:require [clojure.java.data :refer [to-java]] [next.jdbc.protocols :as p]) (:import (java.sql Connection DriverManager)