pmacs-activerecord-oracle_enhanced-adapter 1.4.2.rc1

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--backtrace

data/Gemfile

@@ -0,0 +1,52 @@
+source 'http://rubygems.org'
+
+group :development do
+  gem 'jeweler', '~> 1.5.1'
+  gem 'rspec', '~> 2.4'
+  gem 'rdoc'
+
+  if ENV['RAILS_GEM_VERSION']
+    gem 'activerecord', "=#{ENV['RAILS_GEM_VERSION']}"
+    gem 'actionpack', "=#{ENV['RAILS_GEM_VERSION']}"
+    gem 'activesupport', "=#{ENV['RAILS_GEM_VERSION']}"
+    case ENV['RAILS_GEM_VERSION']
+    when /^2.0/
+      gem 'composite_primary_keys', '=0.9.93'
+    when /^2.1/
+      gem 'composite_primary_keys', '=1.0.8'
+    when /^2.2/
+      gem 'composite_primary_keys', '=2.2.2'
+    when /^2.3.3/
+      gem 'composite_primary_keys', '=2.3.2'
+    when /^3/
+      gem 'railties', "=#{ENV['RAILS_GEM_VERSION']}"
+    end
+  else
+    %w(activerecord activemodel activesupport actionpack railties).each do |gem_name|
+      if ENV['RAILS_GEM_PATH']
+        gem gem_name, :path => File.join(ENV['RAILS_GEM_PATH'], gem_name)
+      else
+        gem gem_name, :git => "git://github.com/rails/rails"
+      end
+    end
+
+    if ENV['AREL_GEM_PATH']
+      gem 'arel', :path => ENV['AREL_GEM_PATH']
+    else
+      gem 'arel', :git => "git://github.com/rails/arel"
+    end
+
+    if ENV['JOURNEY_GEM_PATH']
+      gem 'journey', :path => ENV['JOURNEY_GEM_PATH']
+    else
+      gem "journey", :git => "git://github.com/rails/journey"
+    end
+  end
+
+  gem 'ruby-plsql', '>=0.4.4'
+
+  platforms :ruby do
+    gem 'ruby-oci8', '>=2.0.4'
+  end
+
+end

data/History.md

@@ -0,0 +1,284 @@
+### 1.4.2.rc1 / 2012-11-13
+
+* Enhancements:
+  * Wordlist option for context index [#154]
+  * Fall back to directly connecting via OracleDriver on JRuby [#163]
+  * Allow slash-prefixed database name in database.yml for using a service [#201]
+* Bug fixes:
+  * Fixed explain plans to work with JDBC and OCI8 [#146]
+  * Fixed various issues with virtual columns [#159]
+  * Fixed SQL structure dump with function indexes [#161]
+  * Fixed broken column remove inside a change_table block [#216]
+  * Dump indexes on virtual columns using the column's name instead of the column expression [#211]
+  * Don't update lobs that haven't changed or are attr_readonly [#212]
+  * Support dirty tracking with rails 3.2.9
+
+### 1.4.1 / 2012-01-27
+
+* Enhancements:
+  * Support for Rails 3.2
+  * Support for ActiveRecord 3.2 explain plans [#116]
+  * Support for ActiveRecord 3.1 statement pool, to avoid `ORA-01000` maximum open cursors exceeded (default `statement_limit` is 250 and can be changed in `database.yml`) [#100]
+  * Added error handling for `rename_table` method in migrations [#137]
+* Bug fixes:
+  * Store primary key as `nil` in cache at first time for table without primary key [#84]
+  * Fixed inserting records with decimal type columns (`ORA-01722` invalid number exceptions) [#130]
+  * Check virtual columns only in models that are using `oracle-enhanced` adapter, to avoid problems when using multiple database adapters [#85]
+  * Don't drop the user in rake `db:create` and `db:drop` tasks [#103]
+  * Don't add `db:create` and `db:drop` when ActiveRecord is not used as the primary datastore [#128]
+  * Quote column names in LOB statements to avoid `ORA-00936` errors [#91]
+  * Don't add the `RETURNING` clause if using `composite_primary_keys` gem [#132]
+  * Added `join_to_update` method that is necessary for ActiveRecord 3.1 to ensure that correct UPDATE statement is generated using `WHERE ... IN` subquery with offset condition
+
+### 1.4.0 / 2011-08-09
+
+* Enhancements:
+  * Support for Rails 3.1
+  * Bind parameter support for exec_insert, exec_update and exec_delete (in ActiveRecord 3.1)
+  * Purge recyclebin on rake db:test:purge
+  * Support transactional context index
+  * Require ojdbc6.jar (on Java 6) or ojdbc5.jar (on Java 5) JDBC drivers
+  * Support for RAW data type
+  * rake db:create and db:drop tasks
+  * Support virtual columns (in Oracle 11g) in schema dump
+  * It is possible to specify default tablespaces for tables, indexes, CLOBs and BLOBs
+  * rename_index migrations method
+  * Search for JDBC driver in ./lib directory of Rails application
+* Bug fixes:
+  * Fixed context index dump when definition is larger than 4000 bytes
+  * Fixed schema dump not to conflict with other database adapters that are used in the same application
+  * Allow $ in table name prefix or suffix
+
+### 1.3.2 / 2011-01-05
+
+* Enhancements:
+  * If no :host or :port is provided then connect with :database name (do not default :host to localhost)
+  * Database connection pool support for JRuby on Tomcat and JBoss application servers
+  * NLS connection parameters support via environment variables or database.yml
+  * Support for Arel 2.0 and latest Rails master branch
+  * Support for Rails 3.1 prepared statements (implemented in not yet released Rails master branch version)
+  * Eager loading of included association with more than 1000 records (implemented in not yet released Rails master branch version)
+* Bug fixes:
+  * Foreign keys are added after table definitions in schema dump to ensure correct order of schema statements
+  * Quote NCHAR and NVARCHAR2 type values with N'...'
+  * Numeric username and/or password in database.yml will be automatically converted to string
+
+### 1.3.1 / 2010-09-09
+
+* Enhancements:
+  * Tested with Rails 3.0.0 release
+  * Lexer options for context index creation
+  * Added Bundler for running adapter specs, added RUNNING_TESTS.rdoc with description how to run specs
+  * Connection to database using :host, :port and :database options
+  * Improved loading of adapter in Rails 3 using railtie
+* Bug fixes:
+  * Fix for custom context index procedure when indexing records with null values
+  * Quote table and column names in write_lobs callback
+  * Fix for incorrect column SQL types when two models use the same table and AR query cache is enabled
+  * Fixes for schema and scructure dump tasks
+  * Fix for handling of zero-length strings in BLOB and CLOB columns
+  * removed String.mb_chars upcase and downcase methods for Ruby 1.9 as Rails 3.0.0 already includes Unicode aware upcase and downcase methods for Ruby 1.9
+  * Fixes for latest ActiveRecord unit tests
+
+### 1.3.0 / 2010-06-21
+
+* Enhancements:
+  * Rails 3.0.0.beta4 and Rails 2.3.x compatible
+  * When used with Rails 3 then works together with Oracle SQL compiler included in Arel gem (http://github.com/rails/arel)
+  * Rails 3: Better support for limit and offset (when possible adds just ROWNUM condition in WHERE clause without using subqueries)
+  * Table and column names are always quoted and in uppercase to avoid the need for checking Oracle reserved words
+  * Full text search index creation (add_context_index and remove_context_index methods in migrations and #contains method in ActiveRecord models)
+  * add_index and remove_index give just warnings on wrong index names (new expected behavior in Rails 2.3.8 and 3.0.0)
+  * :tablespace and :options options for create_table and add_index
+* Workarounds:
+  * Rails 3: set ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.cache_columns = true in initializer file for all environments
+    (to avoid too many data dictionary queries from Arel)
+  * Rails 2.3: patch several ActiveRecord methods to work correctly with quoted table names in uppercase (see oracle_enhanced_activerecord_patches.rb).
+    These patches are already included in Rails 3.0.0.beta4.
+* Bug fixes:
+  * Fixes for schema purge (drop correctly materialized views)
+  * Fixes for schema dump and structure dump (use correct statement separator)
+  * Only use Oracle specific schema dump for Oracle connections
+
+### 1.2.4 / 2010-02-23
+
+* Enhancements:
+  * rake db:test:purge will drop all schema objects from test schema (including views, synonyms, packages, functions, procedures) -
+    they should be always reloaded before tests run if necessary
+  * added views, synonyms, packages, functions, procedures, indexes, triggers, types, primary, unique and foreign key constraints to structure dump
+  * added :temporary option for create_table to create temporary tables
+  * added :tablespace option for add_index
+  * support function based indexes in schema dump
+  * support JNDI database connections in JRuby
+  * check ruby-oci8 minimum version 2.0.3
+  * added savepoints support (nested ActiveRecord transactions)
+* Bug fixes:
+  * typecast returned BigDecimal integer values to Fixnum or Bignum
+    (to avoid issues with _before_type_cast values for id attributes because _before_type_cast is used in form helpers)
+  * clear table columns cache after columns definition change in migrations
+
+### 1.2.3 / 2009-12-09
+
+* Enhancements
+  * support fractional seconds in TIMESTAMP values
+  * support for ActiveRecord 2.3.5
+  * use ENV['TZ'] to set database session time zone
+    (as a result DATE and TIMESTAMP values are retrieved with correct time zone)
+  * added cache_columns adapter option
+  * added current_user adapter method
+  * added set_integer_columns and set_string_columns ActiveRecord model class methods
+* Bug fixes:
+  * do not raise exception if ENV['PATH'] is nil
+  * do not add change_table behavior for ActiveRecord 2.0 (to avoid exception during loading)
+  * move foreign key definitions after definition of all tables in schema.rb
+    (to avoid definition of foreign keys before all tables are created)
+  * changed timestamp format mask to use ':' before fractional seconds
+    (workaround to avoid table detection in tables_in_string method in ActiveRecord associations.rb file)
+  * fixed custom create/update/delete methods with ActiveRecord 2.3+ and timestamps
+  * do not call oracle_enhanced specific schema dump methods when using other database adapters
+
+### 1.2.2 / 2009-09-28
+
+* Enhancements
+  * improved RDoc documentation of public methods
+  * structure dump optionally (database.yml environment has db_stored_code: yes) extracts
+    packages, procedures, functions, views, triggers and synonyms
+  * automatically generated too long index names are shortened down to 30 characters
+  * create tables with primary key triggers
+  * use 'set_sequence_name :autogenerated' for inserting into legacy tables with trigger populated primary keys
+  * access to tables over database link (need to define local synonym to remote table and use local synonym in set_table_name)
+  * [JRuby] support JDBC connection using TNS_ADMIN environment variable and TNS database alias
+  * changed cursor_sharing option default from 'similar' to 'force'
+  * optional dbms_output logging to ActiveRecord log file (requires ruby-plsql gem)
+  * use add_foreign_key and remove_foreign_key to define foreign key constraints
+    (the same syntax as in http://github.com/matthuhiggins/foreigner and similar
+    to http://github.com/eyestreet/active_record_oracle_extensions)
+  * raise RecordNotUnique and InvalidForeignKey exceptions if caused by corresponding ORA errors
+    (these new exceptions are supported just by current ActiveRecord master branch)
+  * implemented disable_referential_integrity
+    (enables safe loading of fixtures in schema with foreign key constraints)
+  * use add_synonym and remove_synonym to define database synonyms
+  * add_foreign_key and add_synonym are also exported to schema.rb
+* Bug fixes:
+  * [JRuby] do not raise LoadError if ojdbc14.jar cannot be required (rely on application server to add it to class path)
+  * [JRuby] 'execute' can be used to create triggers with :NEW reference
+  * support create_table without a block
+  * support create_table with Symbol table name
+  * use ActiveRecord functionality to do time zone conversion
+  * rake tasks such as db:test:clone are redefined only if oracle_enhanced is current adapter in use
+  * VARCHAR2 and CHAR column sizes are defined in characters and not in bytes (expected behavior from ActiveRecord)
+  * set_date_columns, set_datetime_columns, ignore_table_columns will work after reestablishing connection
+  * ignore :limit option for :text and :binary columns in migrations
+  * patches for ActiveRecord schema dumper to remove table prefixes and suffixes from schema.rb
+
+### 1.2.1 / 2009-06-07
+
+* Enhancements
+  * caching of table indexes query which makes schema dump much faster
+* Bug fixes:
+  * return Date (and not DateTime) values for :date column value before year 1970
+  * fixed after_create/update/destroy callbacks with plsql custom methods
+  * fixed creation of large integers in JRuby
+  * Made test tasks respect RAILS_ENV
+  * fixed support for composite primary keys for tables with LOBs
+
+### 1.2.0 / 2009-03-22
+
+* Enhancements
+  * support for JRuby and JDBC
+  * support for Ruby 1.9.1 and ruby-oci8 2.0
+  * support for Rails 2.3
+  * quoting of Oracle reserved words in table names and column names
+  * emulation of OracleAdapter (for ActiveRecord unit tests)
+* Bug fixes:
+  * several bug fixes that were identified during running of ActiveRecord unit tests
+
+### 1.1.9 / 2009-01-02
+
+* Enhancements
+  * Added support for table and column comments in migrations
+  * Added support for specifying sequence start values
+  * Added :privilege option (e.g. :SYSDBA) to ActiveRecord::Base.establish_connection
+* Bug fixes:
+  * Do not mark empty decimals, strings and texts (stored as NULL in database) as changed when reassigning them (starting from Rails 2.1)
+  * Create booleans as VARCHAR2(1) columns if emulate_booleans_from_strings is true
+
+### 1.1.8 / 2008-10-10
+
+* Bug fixes:
+  * Fixed storing of serialized LOB columns
+  * Prevent from SQL injection in :limit and :offset
+  * Order by LOB columns (by replacing column with function which returns first 100 characters of LOB)
+  * Sequence creation for tables with non-default primary key in create_table block
+  * Do count distinct workaround only when composite_primary_keys gem is used
+    (otherwise count distinct did not work with ActiveRecord 2.1.1)
+  * Fixed rake db:test:clone_structure task
+    (see http://rsim.lighthouseapp.com/projects/11468/tickets/11-rake-dbtestclone_structure-fails-in-117)
+  * Fixed bug when ActiveRecord::Base.allow_concurrency = true
+    (see http://dev.rubyonrails.org/ticket/11134)
+
+### 1.1.7 / 2008-08-20
+
+* Bug fixes:
+  * Fixed that adapter works without ruby-plsql gem (in this case just custom create/update/delete methods are not available)
+
+### 1.1.6 / 2008-08-19
+
+* Enhancements:
+  * Added support for set_date_columns and set_datetime_columns
+  * Added support for set_boolean_columns
+  * Added support for schema prefix in set_table_name (removed table name quoting)
+  * Added support for NVARCHAR2 column type
+* Bug fixes:
+  * Do not call write_lobs callback when custom create or update methods are defined
+    
+### 1.1.5 / 2008-07-27
+
+* Bug fixes:
+  * Fixed that write_lobs callback works with partial_updates enabled (added additional record lock before writing BLOB data to database)
+* Enhancements:
+  * Changed SQL SELECT in indexes method so that it will execute faster on some large data dictionaries
+  * Support for other date and time formats when assigning string to :date or :datetime column
+
+### 1.1.4 / 2008-07-14
+
+* Enhancements:
+  * Date/Time quoting changes to support composite_primary_keys
+  * Added additional methods that are used by composite_primary_keys
+
+### 1.1.3 / 2008-07-10
+
+* Enhancements:
+  * Added support for custom create, update and delete methods when working with legacy databases where
+    PL/SQL API should be used for create, update and delete operations
+
+### 1.1.2 / 2008-07-08
+
+* Bug fixes:
+  * Fixed after_save callback addition for session store in ActiveRecord version 2.0.2
+  * Changed date column name recognition - now should match regex /(^|_)date(_|$)/i
+    (previously "updated_at" was recognized as :date column and not as :datetime)
+
+### 1.1.1 / 2008-06-28
+
+* Enhancements:
+  * Added ignore_table_columns option
+  * Added support for TIMESTAMP columns (without fractional seconds)
+  * NLS_DATE_FORMAT and NLS_TIMESTAMP_FORMAT independent DATE and TIMESTAMP columns support
+* Bug fixes:
+  * Checks if CGI::Session::ActiveRecordStore::Session does not have enhanced_write_lobs callback before adding it
+    (Rails 2.0 does not add this callback, Rails 2.1 does)
+
+### 1.1.0 / 2008-05-05
+
+* Forked from original activerecord-oracle-adapter-1.0.0.9216
+* Renamed oracle adapter to oracle_enhanced adapter
+  * Added "enhanced" to method and class definitions so that oracle_enhanced and original oracle adapter
+    could be used simultaniously
+  * Added Rails rake tasks as a copy from original oracle tasks
+* Enhancements:
+  * Improved perfomance of schema dump methods when used on large data dictionaries
+  * Added LOB writing callback for sessions stored in database
+  * Added emulate_dates_by_column_name option
+  * Added emulate_integers_by_column_name option
+  * Added emulate_booleans_from_strings option

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2011 Graham Jenkins, Michael Schoen, Raimonds Simanovskis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,403 @@
+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.1.0'
+
+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 you're connecting to a service name, indicate the service with a
+leading slash on the database parameter:
+
+    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_class = ActiveRecord::Base
+
+### Oracle CONTEXT index support
+
+Every edition of Oracle database includes [Oracle Text](http://www.oracle.com/technology/products/text/index.html) option for free which provides several full text indexing capabilities. Therefore in Oracle database case you don’t need external full text indexing and searching engines which can simplify your application deployment architecture.
+
+To create simple single column index create migration with, e.g.
+
+    add_context_index :posts, :title
+
+and you can remove context index with
+
+    remove_context_index :posts, :title
+
+Include in class definition
+
+    has_context_index
+
+and then you can do full text search with
+
+    Post.contains(:title, 'word')
+
+You can create index on several columns (which will generate additional stored procedure for providing XML document with specified columns to indexer):
+
+    add_context_index :posts, [:title, :body]
+
+And you can search either in all columns or specify in which column you want to search (as first argument you need to specify first column name as this is the column which is referenced during index creation):
+
+    Post.contains(:title, 'word')
+    Post.contains(:title, 'word within title')
+    Post.contains(:title, 'word within body')
+
+See Oracle Text documentation for syntax that you can use in CONTAINS function in SELECT WHERE clause.
+
+You can also specify some dummy main column name when creating multiple column index as well as specify to update index automatically after each commit (as otherwise you need to synchronize index manually or schedule periodic update):
+
+    add_context_index :posts, [:title, :body], :index_column => :all_text, :sync => 'ON COMMIT'
+
+    Post.contains(:all_text, 'word')
+
+Or you can specify that index should be updated when specified columns are updated (e.g. in ActiveRecord you can specify to trigger index update when created_at or updated_at columns are updated). Otherwise index is updated only when main index column is updated.
+
+    add_context_index :posts, [:title, :body], :index_column => :all_text,
+      :sync => 'ON COMMIT', :index_column_trigger_on => [:created_at, :updated_at]
+
+And you can even create index on multiple tables by providing SELECT statements which should be used to fetch necessary columns from related tables:
+
+    add_context_index :posts,
+      [:title, :body,
+      # specify aliases always with AS keyword
+      "SELECT comments.author AS comment_author, comments.body AS comment_body FROM comments WHERE comments.post_id = :id"
+      ],
+      :name => 'post_and_comments_index',
+      :index_column => :all_text,
+      :index_column_trigger_on => [:updated_at, :comments_count],
+      :sync => 'ON COMMIT'
+
+    # search in any table columns
+    Post.contains(:all_text, 'word')
+    # search in specified column
+    Post.contains(:all_text, "aaa within title")
+    Post.contains(:all_text, "bbb within comment_author")
+
+### Oracle virtual collumns support
+
+Since version R11G1 Oracle database allows adding computed [Virtual Columns](http://www.oracle-base.com/articles/11g/virtual-columns-11gr1.php) to the table.
+They can be used as normal fields in the queries, in the foreign key contstraints and to partitioning data.
+
+To define virtual column you can use `virtual` method in the `create_table` block, providing column expression in the `:as` option:
+
+    create_table :mytable do |t|
+        t.decimal :price, :precision => 15, :scale => 2
+        t.decimal :quantity, :precision => 15, :scale => 2
+        t.virtual :amount, :as => 'price * quantity'
+    end
+
+Oracle tries to predict type of the virtual column, based on its expression but sometimes it is necessary to state type explicitly.
+This can be done by providing `:type` option to the `virtual` method:
+
+    ...
+    t.virtual :amount_2, :as => 'ROUND(price * quantity,2)', :type => :decimal, :precision => 15, :scale => 2
+    t.virtual :amount_str, :as => "TO_CHAR(quantity) || ' x ' || TO_CHAR(price) || ' USD = ' || TO_CHAR(quantity*price) || ' USD'",
+        :type => :string, :limit => 100
+    ...
+
+It is possible to add virtual column to existing table:
+
+    add_column :mytable, :amount_4, :virtual, :as => 'ROUND(price * quantity,4)', :precision => 38, :scale => 4
+
+You can use the same options here as in the `create_table` `virtual` method.
+
+Changing virtual columns is also possible:
+
+    change_column :mytable, :amount, :virtual, :as => 'ROUND(price * quantity,0)', :type => :integer
+
+Virtual columns allowed in the foreign key constraints.
+For example it can be used to force foreign key constraint on polymorphic association:
+
+    create_table :comments do |t|
+      t.string :subject_type
+      t.integer :subject_id
+      t.virtual :subject_photo_id, :as => "CASE subject_type WHEN 'Photo' THEN subject_id END"
+      t.virtual :subject_event_id, :as => "CASE subject_type WHEN 'Event' THEN subject_id END"
+    end
+
+    add_foreign_key :comments, :photos, :column => :subject_photo_id
+    add_foreign_key :comments, :events, :column => :subject_event_id
+
+For backward compatibility reasons it is possible to use `:default` option in the `create_table` instead of `:as` option.
+But this is deprecated and may be removed in the future version.
+
+### Oracle specific schema statements and data types
+
+There are several additional schema statements and data types available that you can use in database migrations:
+
+  * `add_foreign_key` and `remove_foreign_key` for foreign key definition (and they are also dumped in `db/schema.rb`)
+  * `add_synonym` and `remove_synonym` for synonym definition (and they are also dumped in `db/schema.rb`)
+  * You can create table with primary key trigger using `:primary_key_trigger => true` option for `create_table`
+  * You can define columns with `raw` type which maps to Oracle's `RAW` type
+  * You can add table and column comments with `:comment` option
+  * Default tablespaces can be specified for tables, indexes, clobs and blobs, for example:
+
+        ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.default_tablespaces =
+          {:clob => 'TS_LOB', :blob => 'TS_LOB', :index => 'TS_INDEX', :table => 'TS_DATA'}
+
+TROUBLESHOOTING
+---------------
+
+### What to do if Oracle enhanced adapter is not working?
+
+Please verify that
+
+ 1. Oracle Instant Client is installed correctly
+    Can you connect to database using sqlnet?
+
+ 2. ruby-oci8 is installed correctly
+    Try something like:
+
+        ruby -rubygems -e "require 'oci8'; OCI8.new('username','password','database').exec('select * from dual') do |r| puts r.join(','); end"
+
+    to verify that ruby-oci8 is working
+
+ 3. Verify that activerecord-oracle_enhanced-adapter is working from irb
+
+        require 'rubygems'
+        gem 'activerecord'
+        gem 'activerecord-oracle_enhanced-adapter'
+        require 'active_record'
+        ActiveRecord::Base.establish_connection(:adapter => "oracle_enhanced", :database => "database",:username => "user",:password => "password")
+
+    and see if it is successful (use your correct database, username and password)
+
+### What to do if Oracle enhanced adapter is not working with Phusion Passenger?
+
+Oracle Instant Client and ruby-oci8 requires that several environment variables are set:
+
+  * `LD_LIBRARY_PATH` (on Linux) or `DYLD_LIBRARY_PATH` (on Mac) should point to Oracle Instant Client directory (where Oracle client shared libraries are located)
+  * `TNS_ADMIN` should point to directory where `tnsnames.ora` file is located
+  * `NLS_LANG` should specify which territory and language NLS settings to use and which character set to use (e.g. `"AMERICAN_AMERICA.UTF8"`)
+
+If this continues to throw "OCI Library Initialization Error (OCIError)", you might also need
+
+  * `ORACLE_HOME` set to full Oracle client installation directory
+
+When Apache with Phusion Passenger (mod_passenger or previously mod_rails) is used for Rails application deployment then by default Ruby is launched without environment variables that you have set in shell profile scripts (e.g. .profile). Therefore it is necessary to set environment variables in one of the following ways:
+
+  * Create wrapper script as described in [Phusion blog](http://blog.phusion.nl/2008/12/16/passing-environment-variables-to-ruby-from-phusion-passenger) or [RayApps::Blog](http://blog.rayapps.com/2008/05/21/using-mod_rails-with-rails-applications-on-oracle)
+  * Set environment variables in the file which is used by Apache before launching Apache worker processes - on Linux it typically is envvars file (look in apachectl or apache2ctl script where it is looking for envvars file) or /System/Library/LaunchDaemons/org.apache.httpd.plist on Mac OS X. See the following [discussion thread](http://groups.google.com/group/oracle-enhanced/browse_thread/thread/c5f64106569fadd0) for more hints.
+
+RUNNING TESTS
+-------------
+
+See [RUNNING_TESTS.md](/rsim/oracle-enhanced/blob/master/RUNNING_TESTS.md) for information how to set up environment and run Oracle enhanced adapter unit tests.
+
+LINKS
+-----
+
+* Source code: http://github.com/rsim/oracle-enhanced
+* Bug reports / Feature requests / Pull requests: http://github.com/rsim/oracle-enhanced/issues
+* Discuss at Oracle enhanced adapter group: http://groups.google.com/group/oracle-enhanced
+* Blog posts about Oracle enhanced adapter can be found at http://blog.rayapps.com/category/oracle_enhanced
+
+LICENSE
+-------
+
+(The MIT License)
+
+Copyright (c) 2008-2011 Graham Jenkins, Michael Schoen, Raimonds Simanovskis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.