Liking cljdoc? Tell your friends :D

clj-dbcp

Clojure wrapper for Apache DBCP2 to create JDBC connections pools.

Usage

On Clojars: https://clojars.org/clj-dbcp

Leiningen coordinates: [clj-dbcp "0.9.0"] (supports Clojure 1.5 through Clojure 1.9, Java 7 or higher)

The recommended way to create a datasource is to call the clj-dbcp.core/make-datasource function, for example:

(make-datasource {:classname "com.mysql.jdbc.Driver"
                  :jdbc-url "jdbc:mysql://localhost/empdb"
                  :username "empuser"
                  :password "s3cr3t"
                  :test-query "SELECT 1;"})

You can also parse a database URL (Heroku style) and use to create datasource:

(make-datasource (parse-url "postgres://foo:bar@heroku.com:5489/hellodb"))

or,

(make-datasource (parse-url (System/getenv "DATABASE_URL")))

Sections below describe which of the keys are applicable to various databases:

JDBC parameters

Required: :classname (string), :jdbc-url (string) Optional: :test-query (string)

Optional keys for all JDBC connections

Keyword argMeaningDefault/special
:propertiesMap of property names and values
:userDatabase username
:usernameDatabase username, same as :user
:passwordDatabase password
:test-queryValidation queryAs per :target
:init-sizeInitial size of connection pool (int)
:min-idleMinimum idle connections in pool (int)
:max-idleMaximum idle connections in pool (int)
:max-activeMaximum active connections in pool (int)-ve=no limit
:pool-pstmt?Whether to pool prepared statementstrue
:max-open-pstmtMaximum open prepared statements (int)
:remove-abandoned?Whether to remove abandoned connectionstrue
:remove-abandoned-timeout-secondsTimeout in seconds (int)300
:log-abandoned?Whether to log abandoned connectionstrue
:lifo-pool?Whether Last-In-First-Out (LIFO) or notfalse
:test-while-idle?Whether validate the idle connectionstrue
:test-on-borrow?Whether validate connections on borrowtrue
:test-on-return?Whether validate connections on returntrue
:test-query-timeoutTimeout (seconds) for validation queries
:millis-between-eviction-runsMillis to sleep between evicting unused connections-1
:min-evictable-millisMillis an object may sit idle before it is evicted1800000
:tests-per-evictionNo. of connections to test during each eviction run3
:cache-state?Whether to cache statetrue

Generic JDBC connections

:adapterRequired keysDesired keys
:jdbc:classname :jdbc-url:test-query

JNDI connections

You can open a JNDI datasource (unlike the JDBC datasource) as follows:

(make-datasource :jndi {:context "java:comp/env/myDataSource"})

or,

(jndi-datasource "java:comp/env/myDataSource")

Example

A typical CRUD example using Derby database is below:

(ns example.app
  (:require [clj-dbcp.core     :as dbcp]
            [clojure.java.jdbc :as sql]))

(def db-derby  ;; an in-memory database instance
  {:datasource
   (dbcp/make-datasource
     {"org.apache.derby.jdbc.EmbeddedDriver"
     "jdbc:derby:memory:foo;create=true;"
     "values(1)"})})

(defn crud
  []
  (let [table :emp
        orig-record {:id 1 :name "Bashir" :age 40}
        updt-record {:id 1 :name "Shabir" :age 50}
        drop-table  #(sql/do-commands "DROP TABLE emp")
        retrieve-fn #(sql/with-query-results rows
                      ["SELECT * FROM emp WHERE id=?" 1]
                      (first rows))]
    (sql/with-connection db-derby
      ;; drop table if pre-exists
      (try (drop-table)
        (catch Exception _)) ; ignore exception
      ;; create table
      (sql/do-commands
        "CREATE TABLE emp (id INTEGER, name VARCHAR(50), age INTEGER)")
      ;; insert
      (sql/insert-values table (keys orig-record) (vals orig-record))
      ;; retrieve
      (println (retrieve-fn))
      ;; update
      (sql/update-values table ["id=?" 1] updt-record)
      ;; drop table
      (drop-table))))

Development Notes

You need Java 7 and Leiningen 2 to build this code. Testing JDBC-ODBC bridge driver requires that you use a Windows machine with ODBC DSNs configured.

Starting up the swank server (if you are going to work using Emacs/Slime):

$ lein2 dev swank

Testing against the dev version:

$ ./run-tests

Testing across several versions of Clojure:

$ ./run-tests.sh all

Contributors

Getting in touch

On GMail: kumar.shantanu(at)gmail.com

On Twitter: @kumarshantanu

License

Copyright © 2012-2016 Shantanu Kumar

Distributed under the Eclipse Public License, the same as Clojure.

Can you improve this documentation? These fine people already did:
Shantanu Kumar & Nandhitha R
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close