Skip to content
ActiveRecord adapter using JDBC for JRuby. Please, support the project at BountySource's
Ruby Java
Latest commit e9366a5 Mar 9, 2016 @kares kares Merge branch '1-3-stable'
* 1-3-stable: (25 commits)
  prepare for 1.3.20
  Retrieve AM::Type::Boolean::FALSE_VALUES for Rails 5.
  backwards compat for previous commit (tracking removed TRUE_VALUES in AR)
  [travis-ci] the system call regression also relates to a Rails change in 4.2
  [travis-ci] allow failures - yanother 9K BC timestamp issue + `` regression on 1.7.19
  [travis-ci] a bit more 9K test targets (with AR 4.1 besides 4.2) + fix oraclejdk8
  [test] trying to reproduce an issue with insert not returning id - without luck (#690)
  only mock mysql / mysql2 error under adapter /mysql/ and make sure db:create works
  use system instead of `` to run dumps (on < 4.0) as it has issues under 1.7.x
  [travis-ci] use latest JRuby 1.7 and do some testing against 9K, default JDK to 7
  [test] maintain 1.8 syntax compatibility
  [test] adjust derby tests to conform to how default values are expected on AR 4.2
  avoid column.default type_cast-ing on AR 4.2 - been causing some nesty bugs ... e.g. on postres as an array 'default' instance has been leaking into models
  [test] rename test file
  [test] adjust array column.default expectations to match AR under MRI on 4.1/4.2
  [test] specify a column default test-case - values should not be type-casted on 4.2
  [rake] test --use-color=t by default
  [test] match all *_test.rb files including those in sub-directories
  appraise latest 4.x versions
  [postgres] data_sources support - backport on AR 4.2 + hide internal constants compilant with rails/rails@d6eac00
Failed to load latest commit information.
activerecord-jdbcderby-adapter boost an ego - standing on the shoulders of AR-JDBC giants + spec lic… Jan 9, 2014
activerecord-jdbch2-adapter [h2] allow jdbch2 adapter to use jdbc-h2 1.4 (fixes #639) Apr 13, 2015
activerecord-jdbchsqldb-adapter boost an ego - standing on the shoulders of AR-JDBC giants + spec lic… Jan 9, 2014
activerecord-jdbcmssql-adapter boost an ego - standing on the shoulders of AR-JDBC giants + spec lic… Jan 9, 2014
activerecord-jdbcmysql-adapter boost an ego - standing on the shoulders of AR-JDBC giants + spec lic… Jan 9, 2014
activerecord-jdbcpostgresql-adapter boost an ego - standing on the shoulders of AR-JDBC giants + spec lic… Jan 9, 2014
activerecord-jdbcsqlite3-adapter allow activerecord-jdbcsqlite3-adapter to work with jdbc-sqlite3 3.8.x Nov 17, 2014
bench review and update our benchmarking setup / readme + added update benc… Apr 27, 2015
gemfiles Merge branch '1-3-stable' Mar 9, 2016
jdbc-derby update apache derby to Jul 3, 2015
jdbc-firebird fix "old" MySQL Connector/J link + (c) 2015 Jun 25, 2015
jdbc-h2 fix "old" MySQL Connector/J link + (c) 2015 Jun 25, 2015
jdbc-hsqldb fix "old" MySQL Connector/J link + (c) 2015 Jun 25, 2015
jdbc-jtds better jdbc- gem summaries + READMEs Jun 18, 2014
jdbc-mariadb update MariaDB's jdbc driver to 1.3.4 Jan 12, 2016
jdbc-mysql update jdbc-mysql to 5.1.38 Feb 4, 2016
jdbc-postgres update to postgres' jdbc driver 9.4-1206 Feb 4, 2016
jdbc-sqlite3 update sqlite-jdbc driver/library to Oct 29, 2015
lib Merge branch '1-3-stable' Mar 9, 2016
rails_generators update jdbc generator - add a few notes that it is only needed on Rai… May 25, 2013
rakelib Merge branch '1-3-stable' Mar 9, 2016
src/java/arjdbc export initConnection on PG driver implementation + access super fiel… Feb 18, 2016
test Merge branch '1-3-stable' Mar 9, 2016
.gitignore Merge branch '1-3-stable' Jun 30, 2015
.travis.yml Merge branch '1-3-stable' Mar 9, 2016
.yardopts update rake + setup yard Jun 27, 2013
Appraisals update appraisals to use mysql2 < 0.4 + i18n gem < 0.7 on Rails 3.2 Oct 26, 2015 add in some more README/CONTRIBUTING notes (e.g. around :git sources) Nov 4, 2014
Gemfile Merge branch '1-3-stable' Oct 28, 2015 Merge branch '1-3-stable' Mar 9, 2016
LICENSE.txt "new" recommended jndi: adapter configuration for less confusion + (c… Jan 9, 2014 update README some May 11, 2015 Added explanation about bundle install with custom Gemfile Oct 21, 2014
Rakefile Fix LocalJumpError: unexpected return May 3, 2015
Rakefile.jdbc share the Rakefile for jdbc gems Jun 18, 2013
activerecord-jdbc-adapter.gemspec stop pushing lib to $LOAD_PATH in .gemspec May 11, 2015
pom.xml OK, seems we at least know why we can not generate JRuby populator cl… Oct 20, 2014

ActiveRecord JDBC Adapter

Gem Version

ActiveRecord-JDBC-Adapter (AR-JDBC) is a database adapter for Rails' ActiveRecord component that can be used with JRuby. It allows use of virtually any JDBC-compliant database with your JRuby on Rails application.

We do support ActiveRecord 3.x and 4.x (also 2.3 is still expected to work) from a single code base. AR-JDBC needs JRuby 1.7.x or 9K (we recommend using the latest and greatest of versions) thus Java >= 1.6 is mandatory.

This README and master targets AR-JDBC 1.4.0 (pre-release) please use the 1-3-stable branch for current stable 1.3.x releases.

The next release 1.4 aims to concentrate on internal refactoring and optimization. We're going to be (slowly) dropping support for all of Rails < 3.2, unless there is demand for these. In which case we kindly hope to receive PRs.


ActiveRecord-JDBC-Adapter provides (built-in) full or nearly full support for: MySQL (and MariaDB), PostgreSQL, SQLite3, Oracle, DB2, MS-SQL* (SQL Server), Firebird, Derby, HSQLDB, H2, and Informix.

Even if you're database product is not listed, there are 3rd party gems built on top of AR-JDBC to handle different data-sources, search at the usual places.

Using ActiveRecord JDBC

Inside Rails

To use AR-JDBC with JRuby on Rails:

  1. Choose the adapter (base is usually fine), the following are pre-packaged :

    • Base JDBC (activerecord-jdbc-adapter) - supports all available databases via JDBC (Java's unified DB interface), but requires you to setup a JDBC driver (which with most open-source drivers means adding another gem to your Gemfile e.g. gem 'jdbc-mysql' just like on MRI), for drivers not packed as gems just add the required jars to the class-path
    • MySQL (activerecord-jdbcmysql-adapter)
    • PostgreSQL (activerecord-jdbcpostgresql-adapter)
    • SQLite3 (activerecord-jdbcsqlite3-adapter)
    • Derby (activerecord-jdbcderby-adapter)
    • HSQLDB (activerecord-jdbchsqldb-adapter)
    • H2 (activerecord-jdbch2-adapter)
    • MSSQL (activerecord-jdbcmssql-adapter) - uses the OSS jTDS driver which might have issues with the latest SQLServer (but should work using the Microsoft JDBC Driver for SQL Server - we recommend using version 4.0) NOTE: jTDS seems no longer maintained, if you're run into issues consider using the official (proprietary) driver.

2a. If you're generating a new Rails application, run the usual :

jruby -S rails new sweetapp

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

You'll need to modify your Gemfile to use the activerecord-jdbc-adapter gem (or one of the helper gems) under JRuby. Change your Gemfile to look something like the following :

gem 'mysql2', platform: :ruby
gem 'jdbc-mysql', platform: :jruby
gem 'activerecord-jdbc-adapter', platform: :jruby
  1. Configure your database.yml in the normal Rails style :
  adapter: mysql2 # or mysql
  database: blog_development
  username: blog
  password: 1234

Legacy Configuration: If you use one of the activerecord-jdbcxxx-adapter gems, you can still put a 'jdbc' prefix in front of the database adapter name, e.g. adapter: jdbcmysql but it's no longer recommended on Rails >= 3.0

For plain JDBC database configurations, you'll need to know the database driver class and URL (do not forget to put the driver .jar(s) on the class-path) e.g. :

  adapter: jdbc
  driver: org.apache.hadoop.hive.jdbc.HiveDriver
  url: jdbc:hive://localhost:10004/default

NOTE: please do not confuse the :url setting with the one introduced in ActiveRecord 4.1, we've been using it for a long time with AR-JDBC and for now should work just fine the "jdbc:xxx" way (passed to the driver directly) ...

For JNDI data sources, you may simply specify the JNDI location as follows, it's recommended to use the same adapter: setting as one would configure when using "bare" (JDBC) connections e.g. :

  adapter: postgresql
  jndi: jdbc/PostgreDS
  # be aware that by default AR defaults to pool: 5
  # there are (unofficial) ways of avoiding AR's pooling
  # one such would be: ActiveRecord::Bogacs::FalsePool

NOTE: any other settings such as database:, username:, properties: make no difference since everything is already configured on the data source end.

Most data-sources will provide you with connection pooling, but ActiveRecord uses an internal pool (with a default size of 5) as well, thus you need to be careful to configure both pools wisely to handle your requirements. If you'd like to "disable" AR's built-in pool try :

JDBC driver specific properties might be set if you use an URL to specify the DB or preferably using the properties: syntax :

  adapter: mysql
  username: blog
  password: blog
  url: "jdbc:mysql://localhost:3306/blog?profileSQL=true"
  properties: # specific to com.mysql.jdbc.Driver
    socketTimeout:  60000
    connectTimeout: 60000

If you're really old school you might want to use AR-JDBC with a DB2 on z/OS :

  adapter: db2
  url: jdbc:db2j:net://mightyzoshost:446/RAILS_DBT1
  schema: DB2XB12
  database: RAILS_DB1
  tablespace: TSDE911
    first_table: TSDE912
  username: business
  password: machines
  # default driver used is :
  # NOTE: AS400 support is deprecated since 1.4 in favor
  # of the standalone activerecord-jdbcas400-adapter gem

More information on (configuring) AR-JDBC might be found on our wiki.

Standalone with ActiveRecord

Once the setup is made (see below) you can establish a JDBC connection like this (e.g. for activerecord-jdbcderby-adapter):

ActiveRecord::Base.establish_connection adapter: 'derby', database: 'db/my-db'

Using Bundler

Proceed as with Rails; specify gem 'activerecord' in your Bundle along with the chosen JDBC adapter (or driver), sample Gemfile for MySQL :

gem 'activerecord', '~> 3.2.18'
gem 'activerecord-jdbcmysql-adapter' # or :
# gem 'mysql2', :platform => :mri # C-driver
# gem 'activerecord-jdbc-adapter', :platform => :jruby
# gem 'jdbc-mysql', :platform => :jruby # J-driver

When you require 'bundler/setup' everything will be set up for you as expected.

You do not need to use the 'helper' activerecord-jdbcxxx-adapter gem we provide but than should make sure an appropriate JDBC driver is available at runtime, in that case simply setup your Gemfile as:

gem 'activerecord', '~> 4.1.6'
gem 'activerecord-jdbc-adapter', '~> 1.3', platform: :jruby
# e.g. for PostgreSQL you'll probably add :
# gem 'pg', platform: :mri
# gem 'jdbc-postgres', platform: :jruby

Without Bundler

Install the needed gems with JRuby, for example:

gem install activerecord -v "~> 3.2"
gem install activerecord-jdbc-adapter --ignore-dependencies

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

jruby -S gem install activerecord-jdbcderby-adapter

Your program should include:

require 'active_record'
require 'activerecord-jdbc-adapter' if defined? JRUBY_VERSION
# or in case you're using the pre-packaged adapter gem :
require 'activerecord-jdbcderby-adapter' if defined? JRUBY_VERSION

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 cachedb-adapter project for more information.


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

git clone git://

You will need to have JDK 7+ to compile the native JRuby extension part.

NOTE: Currently, one also needs to make sure to install all of the gem's development dependencies to make sure the compilation javac task does found it's dependent (Java) classes.

Please note that the project manages multiple gems from a single repository, if you're using Bundler >= 1.2 it should be able to locate all gemspecs from the git repository. Sample Gemfile for running with (MySQL) master:

gem 'activerecord-jdbc-adapter', :github => 'jruby/activerecord-jdbc-adapter'

Getting Involved

Please read our CONTRIBUTING & RUNNING_TESTS guides for starters. You can always help us by maintaining AR-JDBC's wiki.


Please report bugs at our issue tracker. If you're not sure if something's a bug, feel free to pre-report it on the mailing lists or ask on the #JRuby IRC channel on (try web-chat).


This project was originally written by Nick Sieger and Ola Bini with lots of help from the community. Polished 3.x compatibility and 4.x support (since AR-JDBC >= 1.3.0) was managed by Karol Bucek among other fellow JRuby-ists.


ActiveRecord-JDBC-Adapter is open-source released under the BSD/MIT license. See LICENSE.txt included with the distribution for details.

Open-source driver gems within AR-JDBC's sources are licensed under the same license the database's drivers are licensed. See each driver gem's LICENSE.txt.

Something went wrong with that request. Please try again.