Source

Clj-DBCP / README

-*- markdown -*-

# Clj-DBCP v0.3

Clj-DBCP is a simple Java-6/Clojure wrapper around the Apache DBCP library for
creating database connection pools and for embedding databases in applications.
The supported operations are:

* BasicDataSource with driver classname, JDBC url, username and password
* Support for validation query, setting connection pool parameters
* Auto-select driver classname and validation query for supported database
* API for memory/filesystem/network based data sources for embedded databases
* Supported+tested: Apache Derby, HSQLDB, H2, CUBRID, MySQL, PostgreSQL
* Supported but not tested: Oracle, IBM DB2, jTDS (SQL Server, Sybase)


## Usage

Maven/Leiningen dependency details are here: [http://clojars.org/org.bituf/clj-dbcp](http://clojars.org/org.bituf/clj-dbcp)

Examples for usage can be found in the tutorial below:


## Building/Installation

You will need Maven 2 or better to build from sources. Execute the following:

    $ mvn clean package  # packages up a JAR in "target" dir
    $ mvn install        # to install to your local Maven repo
    $ mvn clojure:gendoc # generate Clojure API documentation


## License

Copyright (C) 2010 Shantanu Kumar (kumar.shantanu at gmail dot com)

Distributed under the Apache 2 License.


# Tutorial

Clj-DBCP can be used after including the following in your
namespace:

    (ns example.app
      (:use org.bituf.clj-dbcp))

This tutorial does not cover the entire API - feel free to browse the
documentation and source code/unit tests.

**Important: You must include the JDBC drivers on the CLASSPATH on your own. If
you are using an Open Source database you may consider using this for drivers:
[https://bitbucket.org/kumarshantanu/oss-jdbc/src](https://bitbucket.org/kumarshantanu/oss-jdbc/src)**


## Create data source for Apache Derby database

    ;; in-memory instance
    (db-spec
      (derby-memory-datasource))

    ;; filesystem instance
    (db-spec
      (derby-filesystem-datasource))

Example usage (example/app.clj):

    (ns example.app
      (:use org.bituf.clj-dbcp)
      (:use [clojure.contrib.sql :as sql :only ()]))
    
    (def db-derby (db-spec
                    (derby-memory-datasource))) ; creates in-memory instance
    
    (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))))


## Create data source for H2 database

    ;; in-memory instance
    (db-spec
      (h2-memory-datasource))

    ;; filesystem instance
    (db-spec
      (h2-filesystem-datasource))

Example usage: see Derby example


## Create data source for HSQLDB/HyperSQL database

    ;; in-memory instance
    (db-spec
      (hsql-memory-datasource))

    ;; filesystem instance
    (db-spec
      (hsql-filesystem-datasource))


## Create data source for SQLite database

    ;; in-memory instance
    (db-spec
      (sqlite-memory-datasource))

    ;; filesystem instance
    (db-spec
      (sqlite-filesystem-datasource))


Example usage: see Derby example


## Create data source for CUBRID database

    (db-spec
      (cubrid-datasource "localhost:33000" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for MySQL database

    (db-spec
      (mysql-datasource "localhost" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for PostgreSQL database

    (db-spec
      (pgsql-datasource "localhost" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for Oracle database

    (db-spec
      (oracle-datasource "localhost" "examplesid" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for IBM DB2 database

    (db-spec
      (db2-datasource "localhost" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for Microsoft SQL Server database

    (db-spec
      (sqlserver-datasource "localhost" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Create data source for Sybase database

    (db-spec
      (sybase-datasource "localhost" "exampledb" "dbuser" "dbpassword"))

Example usage: see Derby example


## Get data source from JNDI (only looked up; must be already connection pooled)

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

Example usage: see Derby example


## Set custom parameters on the datasource

    (db-spec
      (let [ds (mysql-datasource "localhost" "exampledb" "dbuser" "secret")]
        ;; set custom validation query
        (set-validation-query! ds "SELECT 1")
        ;; set maximum number of active connections on the datasource at a time
        (set-max-active! ds 15)
        ;; set minimum and maximum number of idle connections on the datasource
        (set-min-max-idle! ds 3 8)
        ds))
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.