Skip to content

Configuration

Jump to bottom Edit New page
Xiaofeng edited this page Apr 3, 2020 · 15 revisions

This page tracks all available AR-JDBC configuration options, accepted system properties as well as Java 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
Add a custom footer
Add a custom sidebar
Clone this wiki locally