= Activerecord-jdbc-adapter

activerecord-jdbc-adapter is a database adapter for Rails' ActiveRecord
component that can be used with JRuby[http://www.jruby.org/]. It allows use of
virtually any JDBC-compliant database with your JRuby on Rails application.

== Databases

Activerecord-jdbc-adapter provides full or nearly full support for:
MySQL, PostgreSQL, SQLite3, Oracle, Microsoft SQL Server, DB2,
FireBird, Derby, HSQLDB, H2, and Informix.

Other databases will require testing and likely a custom configuration module.
Please join the JRuby mailing-list[http://jruby.org/community] to help us discover
support for more databases.

== Using ActiveRecord JDBC

=== Inside Rails

To use activerecord-jdbc-adapter with JRuby on Rails:

1. Choose the adapter you wish to gem install. The following pre-packaged
adapters are available:

  * base jdbc (<tt>activerecord-jdbc-adapter</tt>). Supports all available databases via JDBC, but requires you to download and manually install the database vendor's JDBC driver .jar file.
  * mysql (<tt>activerecord-jdbcmysql-adapter</tt>)
  * postgresql (<tt>activerecord-jdbcpostgresql-adapter</tt>)
  * sqlite3 (<tt>activerecord-jdbcsqlite3-adapter</tt>)
  * derby (<tt>activerecord-jdbcderby-adapter</tt>)
  * hsqldb (<tt>activerecord-jdbchsqldb-adapter</tt>)
  * h2 (<tt>activerecord-jdbch2-adapter</tt>)
  * mssql (<tt>activerecord-jdbcmssql-adapter</tt>)

2a. For Rails 3, if you're generating a new application, use the
following command to generate your application:

   jruby -S rails new sweetapp

2b. Otherwise, you'll need to perform some extra configuration steps
to prepare your Rails application for JDBC.

If you're using Rails 3, you'll need to modify your Gemfile to use the
activerecord-jdbc-adapter gem under JRuby. Change your Gemfile to look
like the following (using sqlite3 as an example):

    platforms :ruby do
      gem 'sqlite3'
    end

    platforms :jruby do
      gem 'jruby-openssl'
      gem 'activerecord-jdbcsqlite3-adapter'
    end

If you're using Rails 2:

    jruby script/generate jdbc

3. Configure your database.yml in the normal Rails style. 

Legacy configuration: If you use one of the convenience
'activerecord-jdbcXXX-adapter' adapters, you can still put a 'jdbc'
prefix in front of the database adapter name as below.

    development:
      adapter: jdbcmysql
      username: blog
      password:
      hostname: localhost
      database: weblog_development

For other databases, you'll need to know the database driver class and
URL. Example:

    development:
      adapter: jdbc
      username: blog
      password:
      driver: com.mysql.jdbc.Driver
      url: jdbc:mysql://localhost:3306/weblog_development

   For JNDI data sources, you may simply specify the JNDI location as follows
   (the adapter will be automatically detected):

    production:
      adapter: jdbc
      jndi: jdbc/mysqldb

   If you're really old school you might want to use ARJDBC with a DB2 on z/OS.

    development:
      adapter: jdbc
      encoding: unicode
      url: jdbc:db2j:net://mightyzoshost:446/RAILS_DBT1
      driver: com.ibm.db2.jcc.DB2Driver
      schema: DB2XB12
      database: RAILS_DB1
      tablespace: TSDE911
      lob_tablespaces:
        first_table: TSDE912
      username: scott
      password: lion

=== Standalone, with ActiveRecord

1. Install the gem with JRuby:

    jruby -S gem install activerecord-jdbc-adapter

If you wish to use the adapter for a specific database, you can
install it directly and a driver gem will be installed as well:

    jruby -S gem install activerecord-jdbcderby-adapter

2. After this you can establish a JDBC connection like this:

    ActiveRecord::Base.establish_connection(
      :adapter => 'jdbcderby',
      :database => "db/my-database"
    )

or like this (but requires that you manually put the driver jar on the classpath):

    ActiveRecord::Base.establish_connection(
      :adapter => 'jdbc',
      :driver => 'org.apache.derby.jdbc.EmbeddedDriver',
      :url => 'jdbc:derby:test_ar;create=true'
    )

== Extending AR-JDBC

You can create your own extension to AR-JDBC for a JDBC-based database
that core AR-JDBC does not support. We've created an example project
for the Intersystems Cache database that you can examine as a
template. See the project for more information at the following URL:

  http://github.com/nicksieger/activerecord-cachedb-adapter

== Getting the source

The source for activerecord-jdbc-adapter is available using git.

  git clone git://github.com/jruby/activerecord-jdbc-adapter.git

== Feedback

Please file bug reports at
http://kenai.com/jira/browse/ACTIVERECORD_JDBC. If you're not sure if
something's a bug, feel free to pre-report it on the mailing lists.

== Project Info

* Mailing Lists: http://jruby.org/community
* Issues: https://github.com/jruby/activerecord-jdbc-adapter/issues
* Source: git://github.com/jruby/activerecord-jdbc-adapter.git

== Running AR-JDBC's Tests

Drivers for 6 open-source databases are included. Provided you have
MySQL installed, you can simply type <tt>jruby -S rake</tt> to run the
tests. A database named <tt>weblog_development</tt> is needed
beforehand with a connection user of "blog" and an empty password. You
alse need to grant "blog" create privileges on
'test_rake_db_create.*'.

If you also have PostgreSQL available, those tests will be run if the
`psql' executable can be found. Also ensure you have a database named
<tt>weblog_development</tt> and a user named "blog" and an empty
password.

If you want rails logging enabled during these test runs you can edit 
test/jdbc_common.rb and add the following line:

require 'db/logger'

== Running AR Tests

To run the current AR-JDBC sources with ActiveRecord, just use the
included "rails:test" task. Be sure to specify a driver and a path to
the ActiveRecord sources.

  jruby -S rake rails:test DRIVER=mysql RAILS=/path/activerecord_source_dir

== Travis Build Status {<img src="https://secure.travis-ci.org/jruby/activerecord-jdbc-adapter.png"/>}[http://travis-ci.org/#!/jruby/activerecord-jdbc-adapter]

== Authors

This project was written by Nick Sieger <nick@nicksieger.com> and Ola Bini
<olabini@gmail.com> with lots of help from the JRuby community.

== License

activerecord-jdbc-adapter is released under a BSD license. See the LICENSE file
included with the distribution for details.

Open-source driver gems for activerecord-jdbc-adapter are licensed under the
same license the database's drivers are licensed. See each driver gem's
LICENSE.txt file for details.