Home

Awesome

next.jdbc Clojure CI Release Clojure CI Develop Clojure CI Pull Request

The next generation of clojure.java.jdbc: a new low-level Clojure wrapper for JDBC-based access to databases.

Featured in Jacek Schae's Learn Reitit Pro online course!

TL;DR

The latest versions on Clojars and on cljdoc:

Clojars cljdoc Slack Join Slack

The documentation on cljdoc.org is for the current version of next.jdbc:

The documentation on GitHub is for develop since the 1.3.955 release -- see the CHANGELOG and then read the corresponding updated documentation on GitHub if you want. Older versions of next.jdbc were published under the seancorfield group ID and you can find older seancorfield/next.jdbc documentation on cljdoc.org.

This project follows the version scheme MAJOR.MINOR.COMMITS where MAJOR and MINOR provide some relative indication of the size of the change, but do not follow semantic versioning. In general, all changes endeavor to be non-breaking (by moving to new names rather than by breaking existing names). COMMITS is an ever-increasing counter of commits since the beginning of this repository.

Note: every commit to the develop branch runs CI (GitHub Actions) and successful runs push a MAJOR.MINOR.999-SNAPSHOT build to Clojars so the very latest version of next.jdbc is always available either via that snapshot on Clojars or via a git dependency on the latest SHA.

Motivation

Why another JDBC library? Why a different API from clojure.java.jdbc?

Those were my three primary drivers. In addition, the db-spec-as-hash-map approach in clojure.java.jdbc has caused a lot of frustration and confusion in the past, especially with the wide range of conflicting options that are supported. next.jdbc is heavily protocol-based so it's easier to mix'n'match how you use it with direct Java JDBC code (and the protocol-based approach contributes to the improved performance overall). There's a much clearer path of db-spec -> DataSource -> Connection now, which should steer people toward more connection reuse and better performing apps.

I also wanted datafy/nav support baked right in (it was added to clojure.java.jdbc back in December 2018 as an undocumented, experimental API in a separate namespace). It is the default behavior for execute! and execute-one!. The protocol-based function next.jdbc.result-set/datafiable-row can be used with plan if you need to add datafy/nav support to rows you are creating in your reduction.

As next.jdbc moved from alpha to beta, the last breaking change was made (renaming reducible! to plan) and the API should be considered stable. Only accretive and fixative changes will be made from now on.

After a month of alpha builds being available for testing, the first beta build was released on May 24th, 2019. A release candidate followed on June 4th and the "gold" (1.0.0) release was on June 12th. In addition to the small, core API in next.jdbc, there are "syntactic sugar" SQL functions (insert!, query, update!, and delete!) available in next.jdbc.sql that are similar to the main API in clojure.java.jdbc. See Migrating from clojure.java.jdbc for more detail about the differences.

Usage

The primary concepts behind next.jdbc are that you start by producing a javax.sql.DataSource. You can create a pooled datasource object using your preferred library (c3p0, hikari-cp, etc). You can use next.jdbc's get-datasource function to create a DataSource from a db-spec hash map or from a JDBC URL (string). The underlying protocol, Sourceable, can be extended to allow more things to be turned into a DataSource (and can be extended via metadata on an object as well as via types).

From a DataSource, either you or next.jdbc can create a java.sql.Connection via the get-connection function. You can specify an options hash map to get-connection to modify the connection that is created: :read-only, :auto-commit.

The primary SQL execution API in next.jdbc is:

In addition, there are API functions to create PreparedStatements (prepare) from Connections, which can be passed to plan, execute!, or execute-one!, and to run code inside a transaction (the transact function and the with-transaction macro).

Since next.jdbc uses raw Java JDBC types, you can use with-open directly to reuse connections and ensure they are cleaned up correctly:

  (let [my-datasource (jdbc/get-datasource {:dbtype "..." :dbname "..." ...})]
    (with-open [connection (jdbc/get-connection my-datasource)]
      (jdbc/execute! connection [...])
      (reduce my-fn init-value (jdbc/plan connection [...]))
      (jdbc/execute! connection [...])))

Usage scenarios

There are three intended usage scenarios that have driven the design of the API:

In addition, convenience functions -- "syntactic sugar" -- are provided to insert rows, run queries, update rows, and delete rows, using the same names as in clojure.java.jdbc. These are in next.jdbc.sql since they involve SQL creation -- they are not considered part of the core API.

More Detailed Documentation

License

Copyright © 2018-2021 Sean Corfield

Distributed under the Eclipse Public License version 1.0.