ActiveRecord JDBC Adapter
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.6.8 (we recommend using the latest and greatest of JRubies) thus Java >= 1.6 is mandatory.
This README and master targets AR-JDBC 1.4 (unreleased) 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 hoping to cover ActiveRecord 4.2 as well. We'll slowly be dropping support for all of Rails < 3.2, unless there's demand for it. In which case we kindly accept PRs e.g. on AR 2.3 time with zone parsing does not assume an UTC time-zone which is some "crazy" stuff to handle esp. when optimizing for speed.
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
To use AR-JDBC with JRuby on Rails:
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 (
- PostgreSQL (
- SQLite3 (
- Derby (
- HSQLDB (
- H2 (
- 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.
- Base JDBC (
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
- Configure your database.yml in the normal Rails style :
development: 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,
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. :
development: 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. :
production: 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 : https://github.com/kares/activerecord-bogacs
JDBC driver specific properties might be set if you use an URL to specify the DB or preferably using the properties: syntax :
production: 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 :
development: adapter: db2 url: jdbc:db2j:net://mightyzoshost:446/RAILS_DBT1 schema: DB2XB12 database: RAILS_DB1 tablespace: TSDE911 lob_tablespaces: first_table: TSDE912 username: business password: machines # default driver used is : #driver: com.ibm.db2.jcc.DB2Driver # 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
ActiveRecord::Base.establish_connection adapter: 'derby', database: 'db/my-db'
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
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
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
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://github.com/jruby/activerecord-jdbc-adapter.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'
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 http://freenode.net/ (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.