Configuration

This page tracks all available AR-JDBC configuration options, accepted system properties as well as Java driver specifics.

• Database Setup
• Adapter Configuration
• System Properties
• Driver Specifics

## Database Config

It's much preferred to not change anything about your database.yml as much as possible esp. the adapter setting. AR-JDBC is perfectly capable of using the same adapter setting as under MRI (e.g. for built-in adapters such as adapter: mysql2). To tune driver specific settings you might provide a JDBC URL string with parameters e.g.

production:
  adapter: mysql2
  username: blog
  password: blog
  url: "jdbc:mysql://localhost:3306/blog?profileSQL=true"

but it is not necessary since you might specify database: and use properties: instead :

production:
  adapter: mysql
  username: blog
  password: blog
  database: blog
  properties: # specific to com.mysql.jdbc.Driver
    profileSQL: true
    connectTimeout: 60000

This way (using the specific adapter: name) you also do not need to remember the Java driver class name since it's resolved specific to the DB adapter, with a plain old adapter: jdbc setting you would need to specify a driver and if your driver is not JDBC 4.0 compliant an alive SQL as well e.g.

staging:
  adapter: jdbc
  url: "jdbc:as400://dbhost/;database name=RAILS_DB1"
  driver: com.ibm.as400.access.AS400JDBCDriver
  connection_alive_sql: "SELECT 1 FROM sysibm.tables FETCH FIRST 1 ROWS ONLY"
  schema: DB2XB12
  username: ferko
  password: suska

this quite extensive configuration could have been avoided simply using :

staging:
  adapter: as400
  database: RAILS_DB1
  schema: DB2XB12
  username: ferko
  password: suska

the connection_alive_sql: setting was only needed as long as you do not use a JDBC 4.0 driver, which in case of JTOpen (7.9) means downloading jtopen_7_9_jdbc40_jdk6.zip instead of the "plain" jtopen_7_9.zip from http://sourceforge.net/projects/jt400/files/JTOpen-full/7.9/ .

NOTE: Always use a JDBC 4.0 compliant driver if possible since AR-JDBC 1.3.0 requires Java 6 at minimum and thus you do have it available within your Java install. Older drivers will still work but might need setting a connection_alive_sql: otherwise we won't be able to check whether a connection is valid (JDBC 4.0 provides a isValid API). This applies mostly to adapter: jdbc as for specific adapters we set a correct alive SQL whenever necessary.

JDBC

• one can change the driver to be used (assuming it's on the class-path) for a specific adapter by specifying driver: (user set configuration values are always kept)
• (built-in) escape processing can be enabled by setting statement_escape_processing: true, it is disabled by default (since 1.3.0) NOTE: MySQL's Connector/J has a known statement processing bug, also it's not implemented correctly by the SQLite JDBC driver

Overrides

• adapter_spec: and adapter_class: values can be changed programatically in case you need to extend/change the adapter behavior

H2/HSQLDB

• when using adapter: hsqldb one might use the mem:/file: prefixes when specifying a database e.g.

test:
  adapter: h2
  database: "mem:testdb"

MSSQL

• our SQLServer adapter configuration accepts the instance:, domain: and appname: config options (jTDS driver)
• using the SQLJDBC driver we support the instance:, domain: and application: options and the integrated_security: flag on Windows (needs sqljdbc_auth.dll) for details see MS-SQL

## Adapter Config

MySQL

• use ArJdbc::MySQL.emulate_booleans = false to disable boolean emulation with TINYINTs ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans = false works as well

Fail-Over

Since AR-JDBC relies on JDBC we inherit whatsoever the driver shoots at us, for the official MySQL Connector/J among others it's fail-over support. This might turn out useful for a number of high-availability scenarios. The support is very simple and you can use it anytime you use our MySQL adapter, just specify multiple hosts e.g. :

production
  adapter: mysql
  host: db1.host.org,db2.host.org
  database: zoo
  username: mia
  properties:
    # autoReconnect: false
    failOverReadOnly: true # default value
    secondsBeforeRetryMaster: 30 # default

Whenever the first (master) host goes down the following hosts will be used (in read-only mode by default) for queries. Please consult the official documentation for how fail-over behaves and what are it's costs (it will only fail-over during connection initialization as long as the autoReconnect property is not set to true) http://dev.mysql.com/doc/refman/5.0/en/connector-j-reference-configuration-properties.html

Oracle

• use ArJdbc::Oracle.emulate_booleans = false to disable boolean emulation with NUMBER(1)

DB2

• use ArJdbc::DB2.emulate_booleans = false to disable boolean emulation
• config.active_record.auto_explain_threshold_in_seconds should be commented for Rails < 4.0

## System (ENV) Properties

System properties are usually configured as JVM command line options and are supported by JRuby binary using the -D-Jname=value syntax.

• adapter loading for AR built-in adapters (a.k.a. also known as the holy 3 - MySQL, PostgreSQL and SQLite3) has been changed to happen lazily (since 1.3.0). If you expect these to be loaded eagerly use a Java property e.g. arjdbc.mysql.eager_load=true

• extension discovery has been disabled (since 1.3.0) to no walk along your installed gems, it's advisable to specify extension gems using Bundler, however in case you need it set arjdbc.extensions.discover=true

• arjdbc.tasks.skip=true can be used to disable loading of AR-JDBC's database tasks

• using arjdbc.debug=true one can get more debugging output (esp. from our Java API)

Dates/Times

Since AR-JDBC 1.3.0 (due ActiveRecord 4.0) the JDBC connection returns type-casted values, this handles cases such as "custom" queries e.g. SELECT CURRENT_DATE() correctly. To support backwards compatibility with AR <= 3.2 this gets disabled based on ActiveRecord::VERSION but users are allowed to change this using the arjdbc.datetime.raw system property (accepted values are true/false)

Booleans

Just like Date/Times boolean values are handled the same way (based on ActiveRecord) and might be user-controlled using the arjdbc.boolean.raw system property (true on <= 3.2 and false for >= 4.0 by default).

PostgreSQL

• setting arjdbc.postgresql.iterval.raw=true will not format native interval values according to the Rails expected format but will use the raw format returned from the driver