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)

• connection_alive_timeout: 3 connection alive validation check (ping) timeout in seconds, value has no default - isValid() check depends on JDBC driver

• (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

• configure_connection: false disables the configure_connection "new connection" initialization call on the adapter (since 1.4.0)

Overrides

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

Derby

• with adapter: derby the default transaction isolation (since 1.3.6) might be tuned :

production:
  adapter: derby
  url: jdbc:derby:memory:InMemoryDB;create=true
  # we force Derby into SERIALIZABLE in 1.2/1.3 (by default)
  # this will likely change in the future - for now to keep
  # the DB system default use: transaction_isolation: false
  transaction_isolation: REPEATABLE_READ

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

PostgreSQL

• some of the PG environment variables are supported (since AR-JDBC 1.3.3) for better compatibility, namely :

• PGHOST
• PGPORT
• PGUSER
• PGDATABASE
• PGPASSWORD
• PGCONNECT_TIMEOUT

MySQL

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

Fail-Over

... and more can be found on the MySQL dedicated wiki page

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 Properties

System properties are usually configured as JVM command line options and are supported by JRuby binary using the -J-Dname=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