September 09, 2010
Rails 3.0 was released recently and therefore I am releasing new Oracle enhanced adapter version 1.3.1 which is tested and updated against latest Rails 3.0.0 version. You can read about main changes in oracle_enhanced adapter for Rails 3 support in my previous blog post. Latest version 1.3.1 mainly contains several bug fixes (which you can find in change log as well as in detailed commit list) as well as several new features that I will describe here.
Usage with Rails 3
I have improved a little bit configuration and loading of oracle_enhanced adapter in Rails 3 and here are the initial steps that you should do to use oracle_enhanced adapter in Rails 3 application. I assume that you are using latest Rails 3.0.0 version as well as latest Bundler 1.0.0 version.
At first you need to include necessary gems in Gemfile of your application:
gem 'ruby-oci8', '~> 2.0.4' gem 'activerecord-oracle_enhanced-adapter', '~> 1.3.1'
It is recommended to use
~> version(requires specified version or later minor version update where only the last digit of version has changed) or
= versionin your Gemfile and not
>=(which might include major version changes). In this way you ensure that your application will not break when major API changes will happen in gem that you are using.
If you want to run your application both on MRI and JRuby then you can specify
platforms :ruby do gem 'ruby-oci8', '~> 2.0.4' end
which will load ruby-oci8 gem only when using MRI 1.8 or 1.9 and not when using JRuby.
If you would like to use the latest development version of oracle_enhanced then change Gemfile to:
gem 'activerecord-oracle_enhanced-adapter', '~> 1.3.1', :git => 'git://github.com/rsim/oracle-enhanced.git'
If you will use also ruby-plsql gem in your application then include as well (and specify version as needed)
gem "ruby-plsql", "~> 0.4.3"
After these changes in Gemfile run
bundle update to install necessary gems and generate corresponding Gemfile.lock.
If you want to use all default oracle_enhanced settings then you need just to specify your database connection in
database.yml, for example, something like this:
development: adapter: oracle_enhanced database: orcl username: user password: secret
and you can start to use Rails with Oracle database. If you would like to change some oracle_enhanced adapter settings then it is recommended to create initializer file
config/initializers/oracle.rb where you can specify necessary defaults, for example:
ActiveSupport.on_load(:active_record) do ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.class_eval do self.emulate_integers_by_column_name = true self.emulate_dates_by_column_name = true self.emulate_booleans_from_strings = true # to ensure that sequences will start from 1 and without gaps self.default_sequence_start_value = "1 NOCACHE INCREMENT BY 1" # other settings ... end end
It is important to use
ActiveSupport.on_load(:active_record) as Rails 3 does lazy loading of all components and we need to ensure that oracle_enhanced adapter defaults are set only after ActiveRecord is loaded.
You can take a look at sample Rails 3 application on Oracle to see sample configuration files that I mentioned here.
Database connection options
There are several ways how to specify database connection in
Using tnsnames.ora file with TNS aliases
If you are using tnsnames.ora file with TNS names and connection descriptions then you need to set TNS_ADMIN environment variable to point to directory where tnsnames.ora file is located. If oracle_enhanced adapter will detect that ENV[‘TNS_ADMIN’] is not empty then it will try to use TNS name in :database parameter to connect to database. So in this case in
database.yml you need to specify:
development: adapter: oracle_enhanced database: connection_name_from_tnsnames username: user password: secret
Connection using tnsnames is supported both for MRI with ruby-oci8 as well as for JRuby with JDBC. Use this option if you would not like to hardcode database server address, port and database name in your application and want to specify separately in
If you do not want to create separate tnsnames.ora file and want to specify database server, port and database name directly in application, then you can specify these options separately in
database.yml file, for example:
development: adapter: oracle_enhanced host: localhost port: 1521 database: orcl username: user password: secret
port default value is 1521 and can be omitted. It is also possible to specify host, port and database name is Oracle specific format in
development: adapter: oracle_enhanced database: //localhost:1521/orcl username: user password: secret
It is also possible to specify TNS connection description directly in
database.yml file (if you do not want to create separate
tnsnames.ora file), for example:
development: adapter: oracle_enhanced database: "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orcl)))" username: user password: secret
Using JNDI connections in JRuby
If you deploy your JRuby application in Java application server that supports JNDI connections then it is possible to specify also JNDI connection in
database.yml file, for example:
production: adapter: oracle_enhanced jndi: "jdbc/jndi_connection_name"
I am not using this connection option but some oracle_enhanced users are using it.
Contributing to oracle_enhanced adapter
But even better if you want some new feature in oracle_enhanced adapter then fork oracle_enhanced git repository and make your changes and send me pull requests for review.
For all changes please add also RSpec tests as well as verify if all existing tests are passing after your changes. I added description how to set up environment for running tests – please let me know if something is missing there.
Big thanks to all contributors who have submitted patches so far :)