An Architect's View

CFML, Clojure, Software Design, Frameworks and more...

An Architect's View

clojure.java.jdbc 0.3.0 alpha 1

April 7, 2013 ·

clojure.java.jdbc 0.2.3 was released in June 2012 and represented the culmination of a lot of maintenance and minor enhancements since I took over the old clojure.contrib.sql project from Stephen C. Gilardi, in order to get it running with Clojure 1.3.0 and move it into the new modular contrib structure that was created to go with that release of Clojure. The journey toward a 1.0.0 contrib release is long and hard, with approval from Clojure/core required for that first major release. Part of that approval process centers around idiomatic Clojure and, while the old c.c.sql library was solid and useful, it wasn't very idiomatic. It had a nested namespace containing implementation functions, it had many mutating operations that were not signaled by "!" in their name, it relied on dynamic (bindable) global variables like *db* and so on.

Although the internal namespace went away in version 0.2.0, this release of java.jdbc is the first real step toward addressing the concerns raised by Clojure/core. It is intended to be backward compatible with 0.2.3 in order to make migration easier, although almost all of the 0.2.3 is now marked as deprecated and will be phased out over the next few minor releases, on the road to 1.0.0.

The new API breaks down into three primary sections:

  • High-level functions to insert!, query, update!, delete!, and a more general execute! function.
  • Updated versions of many lower-level functions from the original API, now prefixed with db- that take the database specification (optionally including an active connection) as the new first argument.
  • An optional DSL - Domain Specific Language - for generating basic SQL.

The old naming strategy approach - which relied on dynamic globals - has also been deprecated in favor of optional keyword arguments that specify how to create SQL entities from Clojure identifiers (keywords), and how to create Clojure identifiers (keywords) from SQL entities.

The README and the additional usage documentation have been updated to show examples of the new API in action.

Tags: clojure

6 responses

  • 1 Kevin Albrecht // Apr 7, 2013 at 9:55 PM

    Hi Sean,

    I use this library every day and appreciate the work you are putting into it. Do you feel it is stable enough in this version to switch, or would you recommend I stick to 0.2.3 until 0.3.0 leaves its alpha state?

    --Kevin
  • 2 Sean Corfield // Apr 8, 2013 at 6:22 PM

    Thanx Kevin!

    It's going to depend on how comfortable you are in general running pre-release builds, how much testing you do as a matter of course, and how much of the old API you rely on***.

    As part of the testing I did for the alpha1 release, I ran the World Singles build/test suite end-to-end with the new version and nothing seemed to break. We're running it in QA now.

    Over the next few weeks, we'll be migrating our code to the new java.jdbc API and will take that to production, no doubt well before the library hits 0.3.0 "gold"!

    We originally went live with Clojure on production with 1.3.0 Alpha 7 or 8 so our tolerance for pre-release software may be higher than yours...

    *** Since the old API's implementation has been almost completely rewritten in terms of the new API, so there's very little of the "old" code left.
  • 3 Dan // Apr 18, 2013 at 3:04 PM

    Any tips on using the create-table function in 0.3.0? I saw the Manipulating Tables with DDL page on github, but I am unsure of how to open a connection, all of the other high level functions just take the database specification map.

    Thanks!
  • 4 Sean Corfield // Apr 19, 2013 at 12:12 AM

    @Dan, you can either wrap it in with-connection or you can use db-do-commands with the create-table-ddl function instead. Better DDL handling is on the roadmap for 0.3.0 - it just didn't make the alpha.
  • 5 Miro // Jul 8, 2013 at 6:19 PM

    Hi Sean,
    I am now in a process of moving to 0.3.0. I really like the changes an appreciate all the effort you are putting in.
    Since "with-connection" macro has been deprecated, I am not sure what is the best way to handle connections and how to perform multiple queries (using query function) within one particular connection.
    It is quite common scenario that after a query I need to perform another query straight away still within the same connection (for instance one have to do this in mysql to retrieve total number of rows - when using SQL_CALC_FOUND_ROWS). This is quite easy to implement when using the with-connection macro.
    According to documentation I guess in 0.3.0 I could be using db-do-commands, but that way I wouldnt get the benefit of query function and clojure.java.jdbc.sql.*
    I dont want to use transactions either (though they would ensure single connection being used).
    I am still quite new to clojure so maybe I am just missing something obvious.

    Thanks!
  • 6 Sean Corfield // Jul 14, 2013 at 6:54 PM

    @Miro, I've started to move the java.jdbc documentation to clojure-doc.org and plan to extend it substantially over the next few months:

    http://clojure-doc.org/articles/ecosystem/java_jdbc/home.html

    One of the things it will tackle is answering questions like yours. One simple answer is just to use a connection pool - the docs provide examples for how to do this with c3p0 and BoneCP (we use c3p0 in production at World Singles).

    Another option would be to explicitly get a connection into a local (in let) and use (add-connection db-spec my-conn) as the argument to query etc, remembering to close the connection afterward (using with-open would help).