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.
AR-JDBC 1.2.x officially supports
ActiveRecord 3.x as well as 2.3,
it's latest version is compatible and requires JRuby 1.6.8+ (but as always we
recommend to use the latest and greatest of JRubies) thus Java 1.6 is needed.
NOTE: version 1.3.x of AR-JDBC adapter strives to provide
4.x compatibility (as well as still supporting 2.3 and 3.x) from a
single code base. It's a recommended update for all AR-JDBC 1.2.x users.
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 to help us discover support for more databases.
Using ActiveRecord JDBC
To use AR-JDBC with JRuby on Rails:
- Choose the adapter you wish to gem install. The following pre-packaged adapters are available:
- Base JDBC (
activerecord-jdbc-adapter) - supports all available databases via JDBC, but requires you to download and manually setup a JDBC driver for the database you're using
- MySQL (
- PostgreSQL (
- SQLite3 (
- Derby (
- HSQLDB (
- H2 (
- MSSQL (
activerecord-jdbcmssql-adapter) - uses the OSS jTDS driver by default which might have issues with the latest SQLServer (does not support SQL Azure)
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 might 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 MySQL as an example):
gem 'mysql', platform: :ruby platforms :jruby do gem 'jruby-openssl' gem 'activerecord-jdbcmysql-adapter' end
If you're using Rails 2.3:
jruby script/generate jdbc
- Configure your database.yml in the normal Rails style:
development: adapter: mysql username: blog password: 1234 host: localhost database: blog_development
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,
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 username: blog password: driver: com.mysql.jdbc.Driver url: jdbc:mysql://localhost:3306/blog_development
For JNDI data sources, you may simply specify the JNDI location as follows (the correct adapter type will be automatically detected):
production: adapter: jdbc jndi: jdbc/PostgreDB
JDBC driver specific properties might be set if you use an URL to specify the DB or using the properties: syntax (available since AR-JDBC 1.2.6):
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: 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
If your SGBD isn't automatically discovered you can force a dialect as well:
development: [...] dialect: as400 # For example
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::Base.establish_connection( adapter: 'derby', database: 'db/my-database' )
or using (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:sample_db;create=true' )
Proceed as with Rails; specify the ActiveRecord gem in your Bundle along with the chosen (JDBC) adapters this time sample Gemfile for MySQL:
gem 'activerecord', '~> 3.2.13' gem 'activerecord-jdbcmysql-adapter', :platform => :jruby
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.0.0' gem 'activerecord-jdbc-adapter', '~> 1.3.0', platform: :jruby
Install the needed gems with JRuby:
jruby -S gem install activerecord activerecord-jdbc-adapter
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
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' gem 'activerecord-jdbcmysql-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).
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.