sonar-3.1.1

activerecord-oracle_enhanced-adapter ==================================== Oracle enhanced adapter for ActiveRecord DESCRIPTION ----------- Oracle enhanced ActiveRecord adapter provides Oracle database access from Ruby on Rails applications. Oracle enhanced adapter can be used from Ruby on Rails versions 2.3.x and 3.x and it is working with Oracle database versions 10g and 11g. INSTALLATION ------------ ### Rails 3 When using Ruby on Rails version 3 then in Gemfile include gem 'activerecord-oracle_enhanced-adapter', '~> 1.4.0' where instead of 1.4.0 you can specify any other desired version. It is recommended to specify version with `~>` which means that use specified version or later patch versions (in this example any later 1.4.x version but not 1.5.x version). Oracle enhanced adapter maintains API backwards compatibility during patch version upgrades and therefore it is safe to always upgrade to latest patch version. If you would like to use latest adapter version from github then specify gem 'activerecord-oracle_enhanced-adapter', :git => 'git://github.com/rsim/oracle-enhanced.git' If you are using MRI 1.8 or 1.9 Ruby implementation then you need to install ruby-oci8 gem as well as Oracle client, e.g. [Oracle Instant Client](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html). Include in Gemfile also ruby-oci8: gem 'ruby-oci8', '~> 2.0.6' If you are using JRuby then you need to download latest [Oracle JDBC driver](http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html) - either ojdbc6.jar for Java 6 or ojdbc5.jar for Java 5. And copy this file to one of these locations: * in `./lib` directory of Rails application * in some directory which is in `PATH` * in `JRUBY_HOME/lib` directory * or include path to JDBC driver jar file in Java `CLASSPATH` After specifying necessary gems in Gemfile run bundle install to install the adapter (or later run `bundle update` to force updating to latest version). ### Rails 2.3 If you don't use Bundler in Rails 2 application then you need to specify gems in `config/environment.rb`, e.g. Rails::Initializer.run do |config| #... config.gem 'activerecord-oracle_enhanced-adapter', :lib => "active_record/connection_adapters/oracle_enhanced_adapter" config.gem 'ruby-oci8' #... end But it is recommended to use Bundler for gem version management also for Rails 2.3 applications (search for instructions in Google). ### Without Rails and Bundler If you want to use ActiveRecord and Oracle enhanced adapter without Rails and Bundler then install it just as a gem: gem install activerecord-oracle_enhanced-adapter USAGE ----- ### Database connection In Rails application `config/database.yml` use oracle_enhanced as adapter name, e.g. development: adapter: oracle_enhanced database: xe username: user password: secret If `TNS_ADMIN` environment variable is pointing to directory where `tnsnames.ora` file is located then you can use TNS connection name in `database` parameter. Otherwise you can directly specify database host, port (defaults to 1521) and database name in the following way: development: adapter: oracle_enhanced host: localhost port: 1521 database: xe username: user password: secret or you can use Oracle specific format in `database` parameter: development: adapter: oracle_enhanced database: //localhost:1521/xe username: user password: secret or you can even use Oracle specific TNS connection description: development: adapter: oracle_enhanced database: "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=xe)))" username: user password: secret If you deploy JRuby on Rails application in Java application server that supports JNDI connections then you can specify JNDI connection as well: development: adapter: oracle_enhanced jndi: "jdbc/jndi_connection_name" You can find other available database.yml connection parameters in [oracle_enhanced_adapter.rb](/rsim/oracle-enhanced/blob/master/lib/active_record/connection_adapters/oracle_enhanced_adapter.rb). There are many NLS settings as well as some other Oracle session settings. ### Adapter settings If you want to change Oracle enhanced adapter default settings then create initializer file e.g. `config/initializers/oracle.rb` specify there necessary defaults, e.g.: # It is recommended to set time zone in TZ environment variable so that the same timezone will be used by Ruby and by Oracle session ENV['TZ'] = 'UTC' ActiveSupport.on_load(:active_record) do ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.class_eval do # id columns and columns which end with _id will always be converted to integers self.emulate_integers_by_column_name = true # DATE columns which include "date" in name will be converted to Date, otherwise to Time self.emulate_dates_by_column_name = true # true and false will be stored as 'Y' and 'N' self.emulate_booleans_from_strings = true # start primary key sequences from 1 (and not 10000) and take just one next value in each session self.default_sequence_start_value = "1 NOCACHE INCREMENT BY 1" # other settings ... end end In case of Rails 2 application you do not need to use `ActiveSupport.on_load(:active_record) do ... end` around settings code block. See other adapter settings in [oracle_enhanced_adapter.rb](/rsim/oracle-enhanced/blob/master/lib/active_record/connection_adapters/oracle_enhanced_adapter.rb). ### Legacy schema support If you want to put Oracle enhanced adapter on top of existing schema tables then there are several methods how to override ActiveRecord defaults, see example: class Employee < ActiveRecord::Base # specify schema and table name set_table_name "hr.hr_employees" # specify primary key name set_primary_key "employee_id" # specify sequence name set_sequence_name "hr.hr_employee_s" # set which DATE columns should be converted to Ruby Date set_date_columns :hired_on, :birth_date_on # set which DATE columns should be converted to Ruby Time set_datetime_columns :last_login_time # set which VARCHAR2 columns should be converted to true and false set_boolean_columns :manager, :active # set which columns should be ignored in ActiveRecord ignore_table_columns :attribute1, :attribute2 end You can also access remote tables over database link using set_table_name "hr_employees@db_link" ### Custom create, update and delete methods If you have legacy schema and you are not allowed to do direct INSERTs, UPDATEs and DELETEs in legacy schema tables and need to use existing PL/SQL procedures for create, updated, delete operations then you should add `ruby-plsql` gem to your application and then define custom create, update and delete methods, see example: class Employee < ActiveRecord::Base # when defining create method then return ID of new record that will be assigned to id attribute of new object set_create_method do plsql.employees_pkg.create_employee( :p_first_name => first_name, :p_last_name => last_name, :p_employee_id => nil )[:p_employee_id] end set_update_method do plsql.employees_pkg.update_employee( :p_employee_id => id, :p_first_name => first_name, :p_last_name => last_name ) end set_delete_method do plsql.employees_pkg.delete_employee( :p_employee_id => id ) end end In addition in `config/initializers/oracle.rb` initializer specify that ruby-plsql should use ActiveRecord database connection: plsql.activerecord_cl