@@ -1,13 +1,13 @@ -= activerecord-oracle_enhanced-adapter += Activerecord Oracle enhanced adapter -* http://rubyforge.org/projects/oracle-enhanced/ +* http://github.com/rsim/oracle-enhanced == DESCRIPTION: Oracle "enhanced" ActiveRecord adapter contains useful additional methods for working with new and legacy Oracle databases from Rails which are extracted from current real projects' monkey patches of original Oracle adapter. -See http://github.com/rsim/oracle-enhanced/wikis for more information. +See http://github.com/rsim/oracle-enhanced/wikis for usage information. For questions and feature discussion please use http://groups.google.com/group/oracle-enhanced @@ -22,12 +22,12 @@ Bugs and enhancement requests can be reported at http://rsim.lighthouseapp.com/p * MRI - requires ruby-oci8 1.x or 2.x library to connect to Oracle * Ruby/YARV 1.9.1 - requires ruby-oci8 2.x library to connect to Oracle unicode_utils gem is recommended for Unicode aware string upcase and downcase - * JRuby - uses JDBC driver ojdbc14.jar to connect to Oracle (should be in JRUBY_HOME/lib or in PATH) + * JRuby - uses JDBC driver ojdbc14.jar to connect to Oracle (should be in JRUBY_HOME/lib or in Java class path) * Requires ruby-plsql gem to support custom create, update and delete methods (but can be used without ruby-plsql if this functionality is not needed) == INSTALL: -* sudo gem install activerecord-oracle_enhanced-adapter +* [sudo] gem install activerecord-oracle_enhanced-adapter == CONTRIBUTORS: README.rdoc @@ -1,19 +1,21 @@ require 'rubygems' -gem 'hoe', '>= 2.1.0' +gem 'hoe', '>= 2.3.0' require 'hoe' require 'fileutils' Hoe.plugin :newgem Hoe.plugin :website -# %w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f } require File.dirname(__FILE__) + '/lib/active_record/connection_adapters/oracle_enhanced_version' +# do not generate dot graphics for RDoc +ENV['NODOT'] = 'true' + # Generate all the Rake tasks # Run 'rake -T' to see list of generated tasks (from gem root directory) $hoe = Hoe.spec('activerecord-oracle_enhanced-adapter') do + developer 'Raimonds Simanovskis', 'raimonds.simanovskis@gmail.com' self.version = ActiveRecord::ConnectionAdapters::OracleEnhancedVersion::VERSION - self.developer('Raimonds Simanovskis', 'raimonds.simanovskis@gmail.com') self.changes = self.paragraphs_of("History.txt", 0..1).join("\n\n") self.rubyforge_name = 'oracle-enhanced' self.summary = "Oracle enhaced adapter for Active Record" @@ -21,11 +23,7 @@ $hoe = Hoe.spec('activerecord-oracle_enhanced-adapter') do ['activerecord', '>= 2.0.0'] ] self.extra_rdoc_files = ['README.rdoc'] - self.clean_globs |= %w[**/.DS_Store tmp *.log] - path = self.rubyforge_name - self.remote_rdoc_dir = File.join(path.gsub(/^#{self.rubyforge_name}\/?/,''), 'rdoc') - self.rsync_args = '-av --delete --ignore-errors' end require 'newgem/tasks' # load /tasks/*.rake Rakefile @@ -1,4 +1,4 @@ -class ActiveRecord::ConnectionAdapters::OracleAdapter < ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter +class ActiveRecord::ConnectionAdapters::OracleAdapter < ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter #:nodoc: def adapter_name 'Oracle' end lib/active_record/connection_adapters/emulation/oracle_adapter.rb @@ -34,7 +34,8 @@ require 'active_record/connection_adapters/oracle_enhanced_connection' module ActiveRecord class Base - def self.oracle_enhanced_connection(config) + # Establishes a connection to the database that's used by all Active Record objects. + def self.oracle_enhanced_connection(config) #:nodoc: if config[:emulate_oracle_adapter] == true # allows the enhanced adapter to look like the OracleAdapter. Useful to pick up # conditionals in the rails activerecord test suite @@ -47,22 +48,22 @@ module ActiveRecord end end - # RSI: specify table columns which should be ifnored + # Specify table columns which should be ignored by ActiveRecord. def self.ignore_table_columns(*args) connection.ignore_table_columns(table_name,*args) end - # RSI: specify which table columns should be treated as date (without time) + # Specify which table columns should be typecasted to Date (without time). def self.set_date_columns(*args) connection.set_type_for_columns(table_name,:date,*args) end - # RSI: specify which table columns should be treated as datetime + # Specify which table columns should be typecasted to Time (or DateTime). def self.set_datetime_columns(*args) connection.set_type_for_columns(table_name,:datetime,*args) end - # RSI: specify which table columns should be treated as booleans + # Specify which table columns should be typecasted to boolean values +true+ or +false+. def self.set_boolean_columns(*args) connection.set_type_for_columns(table_name,:boolean,*args) end @@ -79,7 +80,7 @@ module ActiveRecord private :enhanced_write_lobs class << self - # RSI: patch ORDER BY to work with LOBs + # patch ORDER BY to work with LOBs def add_order_with_lobs!(sql, order, scope = :auto) if connection.is_a?(ConnectionAdapters::OracleEnhancedAdapter) order = connection.lob_order_by_expression(self, order) if order @@ -98,11 +99,13 @@ module ActiveRecord add_order_without_lobs!(sql, order, scope = :auto) end private :add_order_with_lobs! + #:stopdoc: alias_method :add_order_without_lobs!, :add_order! alias_method :add_order!, :add_order_with_lobs! + #:startdoc: end - # RSI: get table comment from schema definition + # Get table comment from schema definition. def self.table_comment connection.table_comment(self.table_name) end @@ -110,24 +113,24 @@ module ActiveRecord module ConnectionAdapters #:nodoc: - class OracleEnhancedColumn < Column #:nodoc: + class OracleEnhancedColumn < Column - attr_reader :table_name, :forced_column_type + attr_reader :table_name, :forced_column_type #:nodoc: - def initialize(name, default, sql_type = nil, null = true, table_name = nil, forced_column_type = nil) + def initialize(name, default, sql_type = nil, null = true, table_name = nil, forced_column_type = nil) #:nodoc: @table_name = table_name @forced_column_type = forced_column_type super(name, default, sql_type, null) end - def type_cast(value) + def type_cast(value) #:nodoc: return guess_date_or_time(value) if type == :datetime && OracleEnhancedAdapter.emulate_dates super end # convert something to a boolean - # RSI: added y as boolean value - def self.value_to_boolean(value) + # added y as boolean value + def self.value_to_boolean(value) #:nodoc: if value == true || value == false value elsif value.is_a?(String) && value.blank? @@ -137,20 +140,20 @@ module ActiveRecord end end - # RSI: convert Time or DateTime value to Date for :date columns - def self.string_to_date(string) + # convert Time or DateTime value to Date for :date columns + def self.string_to_date(string) #:nodoc: return string.to_date if string.is_a?(Time) || string.is_a?(DateTime) super end - # RSI: convert Date value to Time for :datetime columns - def self.string_to_time(string) + # convert Date value to Time for :datetime columns + def self.string_to_time(string) #:nodoc: return string.to_time if string.is_a?(Date) && !OracleEnhancedAdapter.emulate_dates super end - # RSI: get column comment from schema definition - # will work only if using default ActiveRecord connection + # Get column comment from schema definition. + # Will work only if using default ActiveRecord connection. def comment ActiveRecord::Base.connection.column_comment(@table_name, name) end @@ -171,7 +174,7 @@ module ActiveRecord when /time/i then :datetime when /decimal|numeric|number/i return :integer if extract_scale(field_type) == 0 - # RSI: if column name is ID or ends with _ID + # if column name is ID or ends with _ID return :integer if OracleEnhancedAdapter.emulate_integers_by_column_name && OracleEnhancedAdapter.is_integer_column?(name, table_name) :decimal else super @@ -186,21 +189,21 @@ module ActiveRecord class <<self protected - def fallback_string_to_date(string) + def fallback_string_to_date(string) #:nodoc: if OracleEnhancedAdapter.string_to_date_format || OracleEnhancedAdapter.string_to_time_format return (string_to_date_or_time_using_format(string).to_date rescue super) end super end - def fallback_string_to_time(string) + def fallback_string_to_time(string) #:nodoc: if OracleEnhancedAdapter.string_to_time_format || OracleEnhancedAdapter.string_to_date_format return (string_to_date_or_time_using_format(string).to_time rescue super) end super end - def string_to_date_or_time_using_format(string) + def string_to_date_or_time_using_format(string) #:nodoc: if OracleEnhancedAdapter.string_to_time_format && dt=Date._strptime(string, OracleEnhancedAdapter.string_to_time_format) return Time.mktime(*dt.values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :wday)) end @@ -211,11 +214,13 @@ module ActiveRecord end - # This is an Oracle/OCI adapter for the ActiveRecord persistence - # framework. It relies upon the OCI8 driver, which works with Oracle 8i - # and above. Most recent development has been on Debian Linux against - # a 10g database, ActiveRecord 1.12.1 and OCI8 0.1.13. - # See: http://rubyforge.org/projects/ruby-oci8/ + # Oracle enhanced adapter will work with both + # Ruby 1.8/1.9 ruby-oci8 gem (which provides interface to Oracle OCI client) + # or with JRuby and Oracle JDBC driver. + # + # It should work with Oracle 9i, 10g and 11g databases. + # Limited set of functionality should work on Oracle 8i as well but several features + # rely on newer functionality in Oracle database. # # Usage notes: # * Key generation assumes a "${table_name}_seq" sequence is available @@ -224,41 +229,77 @@ module ActiveRecord # sequences are created automatically. # * Oracle uses DATE or TIMESTAMP datatypes for both dates and times. # Consequently some hacks are employed to map data back to Date or Time - # in Ruby. If the column_name ends in _time it's created as a Ruby Time. - # Else if the hours/minutes/seconds are 0, I make it a Ruby Date. Else - # it's a Ruby Time. This is a bit nasty - but if you use Duck Typing - # you'll probably not care very much. In 9i and up it's tempting to - # map DATE to Date and TIMESTAMP to Time, but too many databases use - # DATE for both. Timezones and sub-second precision on timestamps are + # in Ruby. Timezones and sub-second precision on timestamps are # not supported. # * Default values that are functions (such as "SYSDATE") are not # supported. This is a restriction of the way ActiveRecord supports # default values. - # * Support for Oracle8 is limited by Rails' use of ANSI join syntax, which - # is supported in Oracle9i and later. You will need to use #finder_sql for - # has_and_belongs_to_many associations to run against Oracle8. # # Required parameters: # # * <tt>:username</tt> # * <tt>:password</tt> - # * <tt>:database</tt> + # * <tt>:database</tt> - either TNS alias or connection string for OCI client or database name in JDBC connection string + # + # Optional parameters: + # + # * <tt>:host</tt> - host name for JDBC connection, defaults to "localhost" + # * <tt>:port</tt> - port number for JDBC connection, defaults to 1521 + # * <tt>:privilege</tt> - set "SYSDBA" if you want to connect with this privilege + # * <tt>:allow_concurrency</tt> - set to "true" if non-blocking mode should be enabled (just for OCI client) + # * <tt>:prefetch_rows</tt> - how many rows should be fetched at one time to increase performance, defaults to 100 + # * <tt>:cursor_sharing</tt> - cursor sharing mode to minimize amount of unique statements, defaults to "similar" + # * <tt>:nls_length_semantics</tt> - semantics of size of VARCHAR2 and CHAR columns, defaults to "CHAR" + # (meaning that size specifies number of characters and not bytes) class OracleEnhancedAdapter < AbstractAdapter - @@emulate_booleans = true + ## + # :singleton-method: + # By default, the OracleEnhancedAdapter will consider all columns of type <tt>NUMBER(1)</tt> + # as boolean. If you wish to disable this emulation you can add the following line + # to your initializer file: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.emulate_booleans = false cattr_accessor :emulate_booleans - - @@emulate_dates = false + self.emulate_booleans = true + + ## + # :singleton-method: + # By default, the OracleEnhancedAdapter will typecast all columns of type <tt>DATE</tt> + # to Time or DateTime (if value is out of Time value range) value. + # If you wish that DATE values with hour, minutes and seconds equal to 0 are typecasted + # to Date then you can add the following line to your initializer file: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.emulate_dates = true + # + # As this option can have side effects when unnecessary typecasting is done it is recommended + # that Date columns are explicily defined with +set_date_columns+ method. cattr_accessor :emulate_dates - - # RSI: set to true if columns with DATE in their name should be emulated as date - @@emulate_dates_by_column_name = false + self.emulate_dates = false + + ## + # :singleton-method: + # By default, the OracleEnhancedAdapter will typecast all columns of type <tt>DATE</tt> + # to Time or DateTime (if value is out of Time value range) value. + # If you wish that DATE columns with "date" in their name (e.g. "creation_date") are typecasted + # to Date then you can add the following line to your initializer file: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.emulate_dates_by_column_name = true + # + # As this option can have side effects when unnecessary typecasting is done it is recommended + # that Date columns are explicily defined with +set_date_columns+ method. cattr_accessor :emulate_dates_by_column_name + self.emulate_dates_by_column_name = false + + # Check column name to identify if it is Date (and not Time) column. + # Is used if +emulate_dates_by_column_name+ option is set to +true+. + # Override this method definition in initializer file if different Date column recognition is needed. def self.is_date_column?(name, table_name = nil) name =~ /(^|_)date(_|$)/i end - # RSI: instance method uses at first check if column type defined at class level - def is_date_column?(name, table_name = nil) + + # instance method uses at first check if column type defined at class level + def is_date_column?(name, table_name = nil) #:nodoc: case get_type_for_column(table_name, name) when nil self.class.is_date_column?(name, table_name) @@ -269,28 +310,58 @@ module ActiveRecord end end - # RSI: set to true if NUMBER columns with ID at the end of their name should be emulated as integers - @@emulate_integers_by_column_name = false + ## + # :singleton-method: + # By default, the OracleEnhancedAdapter will typecast all columns of type <tt>NUMBER</tt> + # (without precision or scale) to Float or BigDecimal value. + # If you wish that NUMBER columns with name "id" or that end with "_id" are typecasted + # to Integer then you can add the following line to your initializer file: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.emulate_integers_by_column_name = true cattr_accessor :emulate_integers_by_column_name + self.emulate_integers_by_column_name = false + + # Check column name to identify if it is Integer (and not Float or BigDecimal) column. + # Is used if +emulate_integers_by_column_name+ option is set to +true+. + # Override this method definition in initializer file if different Integer column recognition is needed. def self.is_integer_column?(name, table_name = nil) name =~ /(^|_)id$/i end - # RSI: set to true if CHAR(1), VARCHAR2(1) columns or VARCHAR2 columns with FLAG or YN at the end of their name - # should be emulated as booleans - @@emulate_booleans_from_strings = false + ## + # :singleton-method: + # If you wish that CHAR(1), VARCHAR2(1) columns or VARCHAR2 columns with FLAG or YN at the end of their name + # are typecasted to booleans then you can add the following line to your initializer file: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.emulate_booleans_from_strings = true cattr_accessor :emulate_booleans_from_strings + self.emulate_booleans_from_strings = false + + # Check column name to identify if it is boolean (and not String) column. + # Is used if +emulate_booleans_from_strings+ option is set to +true+. + # Override this method definition in initializer file if different boolean column recognition is needed. def self.is_boolean_column?(name, field_type, table_name = nil) return true if ["CHAR(1)","VARCHAR2(1)"].include?(field_type) field_type =~ /^VARCHAR2/ && (name =~ /_flag$/i || name =~ /_yn$/i) end + + # How boolean value should be quoted to String. + # Used if +emulate_booleans_from_strings+ option is set to +true+. def self.boolean_to_string(bool) bool ? "Y" : "N" end - # RSI: use to set NLS specific date formats which will be used when assigning string to :date and :datetime columns - @@string_to_date_format = @@string_to_time_format = nil - cattr_accessor :string_to_date_format, :string_to_time_format + # Specify non-default date format that should be used when assigning string values to :date columns, e.g.: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.string_to_date_format = “%d.%m.%Y” + cattr_accessor :string_to_date_format + self.string_to_date_format = nil + + # Specify non-default time format that should be used when assigning string values to :datetime columns, e.g.: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.string_to_time_format = “%d.%m.%Y %H:%M:%S” + cattr_accessor :string_to_time_format + self.string_to_time_format = nil def initialize(connection, logger = nil) #:nodoc: super @@ -314,37 +385,29 @@ module ActiveRecord :float => { :name => "NUMBER" }, :decimal => { :name => "DECIMAL" }, :datetime => { :name => "DATE" }, - # RSI: changed to native TIMESTAMP type + # changed to native TIMESTAMP type # :timestamp => { :name => "DATE" }, :timestamp => { :name => "TIMESTAMP" }, :time => { :name => "DATE" }, :date => { :name => "DATE" }, :binary => { :name => "BLOB" }, - # RSI: if emulate_booleans_from_strings then store booleans in VARCHAR2 + # if emulate_booleans_from_strings then store booleans in VARCHAR2 :boolean => emulate_booleans_from_strings ? { :name => "VARCHAR2", :limit => 1 } : { :name => "NUMBER", :limit => 1 } } end - def table_alias_length + def table_alias_length #:nodoc: 30 end - # Returns an array of arrays containing the field values. - # Order is the same as that returned by #columns. - def select_rows(sql, name = nil) - # last parameter indicates to return also column list - result, columns = select(sql, name, true) - result.map{ |v| columns.map{|c| v[c]} } - end - # QUOTING ================================================== # # see: abstract/quoting.rb - # camelCase column names need to be quoted; not that anyone using Oracle - # would really do this, but handling this case means we pass the test... def quote_column_name(name) #:nodoc: + # camelCase column names need to be quoted; not that anyone using Oracle + # would really do this, but handling this case means we pass the test... @quoted_column_names[name] = name.to_s =~ /[A-Z]/ ? "\"#{name}\"" : quote_oracle_reserved_words(name) end @@ -352,14 +415,14 @@ module ActiveRecord # contain letters, digits, _, $ or # # can be prefixed with schema name # CamelCase table names should be quoted - def self.valid_table_name?(name) + def self.valid_table_name?(name) #:nodoc: name = name.to_s name =~ /^([A-Za-z_0-9]+\.)?[a-z][a-z_0-9\$#]*$/ || name =~ /^([A-Za-z_0-9]+\.)?[A-Z][A-Z_0-9\$#]*$/ ? true : false end - # abstract_adapter calls quote_column_name from quote_table_name, so prevent that - def quote_table_name(name) + def quote_table_name(name) #:nodoc: + # abstract_adapter calls quote_column_name from quote_table_name, so prevent that @quoted_table_names[name] ||= if self.class.valid_table_name?(name) name else @@ -376,10 +439,10 @@ module ActiveRecord case column.type when :text, :binary %Q{empty_#{ column.sql_type.downcase rescue 'blob' }()} - # RSI: TIMESTAMP support + # NLS_DATE_FORMAT independent TIMESTAMP support when :timestamp quote_timestamp_with_to_timestamp(value) - # RSI: NLS_DATE_FORMAT independent DATE support + # NLS_DATE_FORMAT independent DATE support when :date, :time, :datetime quote_date_with_to_date(value) else @@ -394,23 +457,23 @@ module ActiveRecord end end - def quoted_true + def quoted_true #:nodoc: return "'#{self.class.boolean_to_string(true)}'" if emulate_booleans_from_strings "1" end - def quoted_false + def quoted_false #:nodoc: return "'#{self.class.boolean_to_string(false)}'" if emulate_booleans_from_strings "0" end - # RSI: should support that composite_primary_keys gem will pass date as string - def quote_date_with_to_date(value) + def quote_date_with_to_date(value) #:nodoc: + # should support that composite_primary_keys gem will pass date as string value = quoted_date(value) if value.acts_like?(:date) || value.acts_like?(:time) "TO_DATE('#{value}','YYYY-MM-DD HH24:MI:SS')" end - def quote_timestamp_with_to_timestamp(value) + def quote_timestamp_with_to_timestamp(value) #:nodoc: # add up to 9 digits of fractional seconds to inserted time value = "#{quoted_date(value)}.#{("%.6f"%value.to_f).split('.')[1]}" if value.acts_like?(:time) "TO_TIMESTAMP('#{value}','YYYY-MM-DD HH24:MI:SS.FF6')" @@ -422,19 +485,21 @@ module ActiveRecord # If SQL statement fails due to lost connection then reconnect # and retry SQL statement if autocommit mode is enabled. # By default this functionality is disabled. + attr_reader :auto_retry #:nodoc: @auto_retry = false - attr_reader :auto_retry - def auto_retry=(value) + + def auto_retry=(value) #:nodoc: @auto_retry = value @connection.auto_retry = value if @connection end + # return raw OCI8 or JDBC connection def raw_connection @connection.raw_connection end # Returns true if the connection is active. - def active? + def active? #:nodoc: # Pings the connection to check if it's still good. Note that an # #active? method is also available, but that simply returns the # last known state, which isn't good enough if the connection has @@ -445,14 +510,14 @@ module ActiveRecord end # Reconnects to the database. - def reconnect! + def reconnect! #:nodoc: @connection.reset! rescue OracleEnhancedConnectionException => e @logger.warn "#{adapter_name} automatic reconnection failed: #{e.message}" end # Disconnects from the database. - def disconnect! + def disconnect! #:nodoc: @connection.logoff rescue nil end @@ -461,10 +526,19 @@ module ActiveRecord # # see: abstract/database_statements.rb - def execute(sql, name = nil) #:nodoc: + # Executes a SQL statement + def execute(sql, name = nil) log(sql, name) { @connection.exec sql } end + # Returns an array of arrays containing the field values. + # Order is the same as that returned by #columns. + def select_rows(sql, name = nil) + # last parameter indicates to return also column list + result, columns = select(sql, name, true) + result.map{ |v| columns.map{|c| v[c]} } + end + # Returns the next sequence value from a sequence generator. Not generally # called directly; used by ActiveRecord to get the next primary key value # when inserting a new database record (see #prefetch_primary_key?). @@ -489,7 +563,7 @@ module ActiveRecord end def add_limit_offset!(sql, options) #:nodoc: - # RSI: added to_i for limit and offset to protect from SQL injection + # added to_i for limit and offset to protect from SQL injection offset = (options[:offset] || 0).to_i if limit = options[:limit] @@ -512,7 +586,7 @@ module ActiveRecord # Inserts the given fixture into the table. Overridden to properly handle lobs. - def insert_fixture(fixture, table_name) + def insert_fixture(fixture, table_name) #:nodoc: super klass = fixture.class_name.constantize rescue nil @@ -522,7 +596,7 @@ module ActiveRecord end # Writes LOB values from attributes, as indicated by the LOB columns of klass. - def write_lobs(table_name, klass, attributes) + def write_lobs(table_name, klass, attributes) #:nodoc: # is class with composite primary key> is_with_cpk = klass.respond_to?(:composite?) && klass.composite? if is_with_cpk @@ -532,7 +606,7 @@ module ActiveRecord end klass.columns.select { |col| col.sql_type =~ /LOB$/i }.each do |col| value = attributes[col.name] - # RSI: changed sequence of next two lines - should check if value is nil before converting to yaml + # changed sequence of next two lines - should check if value is nil before converting to yaml next if value.nil? || (value == '') value = value.to_yaml if col.text? && klass.serialized_attributes[col.name] uncached do @@ -548,9 +622,9 @@ module ActiveRecord end end - # RSI: change LOB column for ORDER BY clause + # change LOB column for ORDER BY clause # just first 100 characters are taken for ordering - def lob_order_by_expression(klass, order) + def lob_order_by_expression(klass, order) #:nodoc: return order if order.nil? changed = false new_order = order.to_s.strip.split(/, */).map do |order_by_col| @@ -573,16 +647,16 @@ module ActiveRecord select_one("select sys_context('userenv','db_name') db from dual")["db"] end - # RSI: changed select from user_tables to all_tables - much faster in large data dictionaries def tables(name = nil) #:nodoc: + # changed select from user_tables to all_tables - much faster in large data dictionaries select_all("select decode(table_name,upper(table_name),lower(table_name),table_name) name from all_tables where owner = sys_context('userenv','session_user')").map {|t| t['name']} end - cattr_accessor :all_schema_indexes + cattr_accessor :all_schema_indexes #:nodoc: # This method selects all indexes at once, and caches them in a class variable. # Subsequent index calls get them from the variable, without going to the DB. - def indexes(table_name, name = nil) + def indexes(table_name, name = nil) #:nodoc: (owner, table_name) = @connection.describe(table_name) unless all_schema_indexes result = select_all(<<-SQL) @@ -616,21 +690,21 @@ module ActiveRecord all_schema_indexes.select{|i| i.table == table_name} end - # RSI: set ignored columns for table - def ignore_table_columns(table_name, *args) + # set ignored columns for table + def ignore_table_columns(table_name, *args) #:nodoc: @ignore_table_columns ||= {} @ignore_table_columns[table_name] ||= [] @ignore_table_columns[table_name] += args.map{|a| a.to_s.downcase} @ignore_table_columns[table_name].uniq! end - def ignored_table_columns(table_name) + def ignored_table_columns(table_name) #:nodoc: @ignore_table_columns ||= {} @ignore_table_columns[table_name] end - # RSI: set explicit type for specified table columns - def set_type_for_columns(table_name, column_type, *args) + # set explicit type for specified table columns + def set_type_for_columns(table_name, column_type, *args) #:nodoc: @table_column_type ||= {} @table_column_type[table_name] ||= {} args.each do |col| @@ -638,16 +712,16 @@ module ActiveRecord end end - def get_type_for_column(table_name, column_name) + def get_type_for_column(table_name, column_name) #:nodoc: @table_column_type && @table_column_type[table_name] && @table_column_type[table_name][column_name.to_s.downcase] end - def clear_types_for_columns + def clear_types_for_columns #:nodoc: @table_column_type = nil end def columns(table_name, name = nil) #:nodoc: - # RSI: get ignored_columns by original table name + # get ignored_columns by original table name ignored_columns = ignored_table_columns(table_name) (owner, desc_table_name) = @connection.describe(table_name) @@ -666,7 +740,7 @@ module ActiveRecord order by column_id SQL - # RSI: added deletion of ignored columns + # added deletion of ignored columns select_all(table_cols, name).delete_if do |row| ignored_columns && ignored_columns.include?(row['name'].downcase) end.map do |row| @@ -686,18 +760,42 @@ module ActiveRecord row['data_default'], row['sql_type'], row['nullable'] == 'Y', - # RSI: pass table name for table specific column definitions + # pass table name for table specific column definitions table_name, - # RSI: pass column type if specified in class definition + # pass column type if specified in class definition get_type_for_column(table_name, oracle_downcase(row['name']))) end end - # RSI: default sequence start with value - @@default_sequence_start_value = 10000 + ## + # :singleton-method: + # Specify default sequence start with value (by default 10000 if not explicitly set), e.g.: + # + # ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.default_sequence_start_value = 1 cattr_accessor :default_sequence_start_value + self.default_sequence_start_value = 10000 - def create_table(name, options = {}, &block) #:nodoc: + # Additional options for +create_table+ method in migration files. + # + # You can specify individual starting value in table creation migration file, e.g.: + # + # create_table :users, :sequence_start_value => 100 do |t| + # # ... + # end + # + # You can also specify other sequence definition additional parameters, e.g.: + # + # create_table :users, :sequence_start_value => “100 NOCACHE INCREMENT BY 10” do |t| + # # ... + # end + # + # It is possible to add table and column comments in table creation migration files: + # + # create_table :employees, :comment => “Employees and contractors” do |t| + # t.string :first_name, :comment => “Given name” + # t.string :last_name, :comment => “Surname” + # end + def create_table(name, options = {}, &block) create_sequence = options[:id] != false column_comments = {} super(name, options) do |t| @@ -752,7 +850,7 @@ module ActiveRecord end # clear cached indexes when adding new index - def add_index(table_name, column_name, options = {}) + def add_index(table_name, column_name, options = {}) #:nodoc: self.all_schema_indexes = nil super end @@ -763,7 +861,7 @@ module ActiveRecord execute "DROP INDEX #{index_name(table_name, options)}" end - def add_column(table_name, column_name, type, options = {}) + def add_column(table_name, column_name, type, options = {}) #:nodoc: add_column_sql = "ALTER TABLE #{quote_table_name(table_name)} ADD #{quote_column_name(column_name)} #{type_to_sql(type, options[:limit], options[:precision], options[:scale])}" options[:type] = type add_column_options!(add_column_sql, options) @@ -774,7 +872,7 @@ module ActiveRecord execute "ALTER TABLE #{quote_table_name(table_name)} MODIFY #{quote_column_name(column_name)} DEFAULT #{quote(default)}" end - def change_column_null(table_name, column_name, null, default = nil) + def change_column_null(table_name, column_name, null, default = nil) #:nodoc: column = column_for(table_name, column_name) unless null || default.nil? @@ -807,18 +905,17 @@ module ActiveRecord execute "ALTER TABLE #{quote_table_name(table_name)} DROP COLUMN #{quote_column_name(column_name)}" end - # RSI: table and column comments - def add_comment(table_name, column_name, comment) + def add_comment(table_name, column_name, comment) #:nodoc: return if comment.blank? execute "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{column_name} IS '#{comment}'" end - def add_table_comment(table_name, comment) + def add_table_comment(table_name, comment) #:nodoc: return if comment.blank? execute "COMMENT ON TABLE #{quote_table_name(table_name)} IS '#{comment}'" end - def table_comment(table_name) + def table_comment(table_name) #:nodoc: (owner, table_name) = @connection.describe(table_name) select_value <<-SQL SELECT comments FROM all_tab_comments @@ -827,7 +924,7 @@ module ActiveRecord SQL end - def column_comment(table_name, column_name) + def column_comment(table_name, column_name) #:nodoc: (owner, table_name) = @connection.describe(table_name) select_value <<-SQL SELECT comments FROM all_col_comments @@ -839,10 +936,10 @@ module ActiveRecord # Find a table's primary key and sequence. # *Note*: Only primary key is implemented - sequence will be nil. - def pk_and_sequence_for(table_name) + def pk_and_sequence_for(table_name) #:nodoc: (owner, table_name) = @connection.describe(table_name) - # RSI: changed select from all_constraints to user_constraints - much faster in large data dictionaries + # changed select from all_constraints to user_constraints - much faster in large data dictionaries pks = select_values(<<-SQL, 'Primary Key') select cc.column_name from user_constraints c, user_cons_columns cc @@ -862,7 +959,7 @@ module ActiveRecord structure << "create sequence #{seq.to_a.first.last};\n\n" end - # RSI: changed select from user_tables to all_tables - much faster in large data dictionaries + # changed select from user_tables to all_tables - much faster in large data dictionaries select_all("select table_name from all_tables where owner = sys_context('userenv','session_user') order by 1").inject(s) do |structure, table| ddl = "create table #{table.to_a.first.last} (\n " cols = select_all(%Q{ @@ -890,7 +987,7 @@ module ActiveRecord end end - # DGS. Extract all stored procedures, packages, synonyms and views. + # Extract all stored procedures, packages, synonyms and views. def structure_dump_db_stored_code #:nodoc: structure = "\n" select_all("select distinct name, type @@ -936,7 +1033,7 @@ module ActiveRecord drop << "drop sequence #{seq.to_a.first.last};\n\n" end - # RSI: changed select from user_tables to all_tables - much faster in large data dictionaries + # changed select from user_tables to all_tables - much faster in large data dictionaries select_all("select table_name from all_tables where owner = sys_context('userenv','session_user') order by 1").inject(s) do |drop, table| drop << "drop table #{table.to_a.first.last} cascade constraints;\n\n" end @@ -973,7 +1070,7 @@ module ActiveRecord # making every row the same. # # distinct("posts.id", "posts.created_at desc") - def distinct(columns, order_by) + def distinct(columns, order_by) #:nodoc: return "DISTINCT #{columns}" if order_by.blank? # construct a valid DISTINCT clause, ie. one that includes the ORDER BY columns, using @@ -989,7 +1086,7 @@ module ActiveRecord # ORDER BY clause for the passed order option. # # Uses column aliases as defined by #distinct. - def add_order_by_for_association_limiting!(sql, options) + def add_order_by_for_association_limiting!(sql, options) #:nodoc: return sql if options[:order].blank? order = options[:order].split(',').collect { |s| s.strip }.reject(&:blank?) @@ -1001,7 +1098,7 @@ module ActiveRecord protected - def translate_exception(exception, message) + def translate_exception(exception, message) #:nodoc: case @connection.error_code(exception) when 1 RecordNotUnique.new(message, exception) @@ -1035,18 +1132,20 @@ module ActiveRecord end end -# RSI: Added LOB writing callback for sessions stored in database +# Added LOB writing callback for sessions stored in database # Otherwise it is not working as Session class is defined before OracleAdapter is loaded in Rails 2.0 if defined?(CGI::Session::ActiveRecordStore::Session) if !CGI::Session::ActiveRecordStore::Session.respond_to?(:after_save_callback_chain) || CGI::Session::ActiveRecordStore::Session.after_save_callback_chain.detect{|cb| cb.method == :enhanced_write_lobs}.nil? + #:stopdoc: class CGI::Session::ActiveRecordStore::Session after_save :enhanced_write_lobs end + #:startdoc: end end -# RSI: load custom create, update, delete methods functionality +# Load custom create, update, delete methods functionality # rescue LoadError if ruby-plsql gem cannot be loaded begin require 'active_record/connection_adapters/oracle_enhanced_procedures' @@ -1057,21 +1156,21 @@ rescue LoadError end end -# RSI: load additional methods for composite_primary_keys support +# Load additional methods for composite_primary_keys support require 'active_record/connection_adapters/oracle_enhanced_cpk' -# RSI: load patch for dirty tracking methods +# Load patch for dirty tracking methods require 'active_record/connection_adapters/oracle_enhanced_dirty' -# RSI: load rake tasks definitions +# Load rake tasks definitions begin require 'active_record/connection_adapters/oracle_enhanced_tasks' rescue LoadError end if defined?(RAILS_ROOT) -# handles quoting of oracle reserved words +# Handles quoting of oracle reserved words require 'active_record/connection_adapters/oracle_enhanced_reserved_words' -# add BigDecimal#to_d, Fixnum#to_d and Bignum#to_d methods if not already present +# Add BigDecimal#to_d, Fixnum#to_d and Bignum#to_d methods if not already present require 'active_record/connection_adapters/oracle_enhanced_core_ext' lib/active_record/connection_adapters/oracle_enhanced_adapter.rb @@ -1,7 +1,7 @@ module ActiveRecord module ConnectionAdapters # interface independent methods - class OracleEnhancedConnection + class OracleEnhancedConnection #:nodoc: def self.create(config) case ORACLE_ENHANCED_CONNECTION @@ -52,7 +52,7 @@ module ActiveRecord end - class OracleEnhancedConnectionException < StandardError + class OracleEnhancedConnectionException < StandardError #:nodoc: end end lib/active_record/connection_adapters/oracle_enhanced_connection.rb @@ -1,7 +1,7 @@ require "bigdecimal" unless BigDecimal.instance_methods.include?("to_d") BigDecimal.class_eval do - def to_d + def to_d #:nodoc: self end end @@ -9,7 +9,7 @@ end unless Bignum.instance_methods.include?("to_d") Bignum.class_eval do - def to_d + def to_d #:nodoc: BigDecimal.new(self.to_s) end end @@ -17,7 +17,7 @@ end unless Fixnum.instance_methods.include?("to_d") Fixnum.class_eval do - def to_d + def to_d #:nodoc: BigDecimal.new(self.to_s) end end @@ -30,22 +30,22 @@ if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby' && RUBY_VERSION >= '1.9' require "unicode_utils/upcase" require "unicode_utils/downcase" - module ActiveRecord - module ConnectionAdapters - module OracleEnhancedUnicodeString - def upcase + module ActiveRecord #:nodoc: + module ConnectionAdapters #:nodoc: + module OracleEnhancedUnicodeString #:nodoc: + def upcase #:nodoc: UnicodeUtils.upcase(self) end - def downcase + def downcase #:nodoc: UnicodeUtils.downcase(self) end end end end - class String - def mb_chars + class String #:nodoc: + def mb_chars #:nodoc: self.extend(ActiveRecord::ConnectionAdapters::OracleEnhancedUnicodeString) self end lib/active_record/connection_adapters/oracle_enhanced_core_ext.rb @@ -2,13 +2,13 @@ module ActiveRecord #:nodoc: module ConnectionAdapters #:nodoc: module OracleEnhancedCpk #:nodoc: - # This mightn't be in Core, but count(distinct x,y) doesn't work for me - # RSI: return that not supported if composite_primary_keys gem is required + # This mightn't be in Core, but count(distinct x,y) doesn't work for me. + # Return that not supported if composite_primary_keys gem is required. def supports_count_distinct? #:nodoc: @supports_count_distinct ||= ! defined?(CompositePrimaryKeys) end - def concat(*columns) + def concat(*columns) #:nodoc: "(#{columns.join('||')})" end lib/active_record/connection_adapters/oracle_enhanced_cpk.rb @@ -2,19 +2,19 @@ module ActiveRecord #:nodoc: module ConnectionAdapters #:nodoc: module OracleEnhancedDirty #:nodoc: - module InstanceMethods + module InstanceMethods #:nodoc: private def field_changed?(attr, old, value) if column = column_for_attribute(attr) - # RSI: added also :decimal type + # Added also :decimal type if (column.type == :integer || column.type == :decimal) && column.null && (old.nil? || old == 0) && value.blank? # For nullable integer columns, NULL gets stored in database for blank (i.e. '') values. # Hence we don't record it as a change if the value changes from nil to ''. # If an old value of 0 is set to '' we want this to get changed to nil as otherwise it'll # be typecast back to 0 (''.to_i => 0) value = nil - # RSI: Oracle stores empty string '' or empty text (CLOB) as NULL + # Oracle stores empty string '' or empty text (CLOB) as NULL # therefore need to convert empty string value to nil if old value is nil elsif (column.type == :string || column.type == :text) && column.null && old.nil? value = nil if value == '' lib/active_record/connection_adapters/oracle_enhanced_dirty.rb @@ -35,7 +35,7 @@ module ActiveRecord module ConnectionAdapters # JDBC database interface for JRuby - class OracleEnhancedJDBCConnection < OracleEnhancedConnection + class OracleEnhancedJDBCConnection < OracleEnhancedConnection #:nodoc: attr_accessor :active alias :active? :active lib/active_record/connection_adapters/oracle_enhanced_jdbc_connection.rb @@ -3,7 +3,7 @@ require 'delegate' begin require 'oci8' unless self.class.const_defined? :OCI8 - # RSI: added mapping for TIMESTAMP / WITH TIME ZONE / LOCAL TIME ZONE types + # added mapping for TIMESTAMP / WITH TIME ZONE / LOCAL TIME ZONE types # currently Ruby-OCI8 does not support fractional seconds for timestamps OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::OraDate OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP_TZ] = OCI8::BindType::OraDate @@ -24,7 +24,7 @@ module ActiveRecord module ConnectionAdapters # OCI database interface for MRI - class OracleEnhancedOCIConnection < OracleEnhancedConnection + class OracleEnhancedOCIConnection < OracleEnhancedConnection #:nodoc: def initialize(config) @raw_connection = OCI8EnhancedAutoRecover.new(config, OracleEnhancedOCIFactory) @@ -289,17 +289,18 @@ end # this would be dangerous (as the earlier part of the implied transaction # may have failed silently if the connection died) -- so instead the # connection is marked as dead, to be reconnected on it's next use. +#:stopdoc: class OCI8EnhancedAutoRecover < DelegateClass(OCI8) #:nodoc: - attr_accessor :active - alias :active? :active + attr_accessor :active #:nodoc: + alias :active? :active #:nodoc: cattr_accessor :auto_retry class << self - alias :auto_retry? :auto_retry + alias :auto_retry? :auto_retry #:nodoc: end @@auto_retry = false - def initialize(config, factory) + def initialize(config, factory) #:nodoc: @active = true @config = config @factory = factory @@ -310,7 +311,7 @@ class OCI8EnhancedAutoRecover < DelegateClass(OCI8) #:nodoc: # Checks connection, returns true if active. Note that ping actively # checks the connection, while #active? simply returns the last # known state. - def ping + def ping #:nodoc: @connection.exec("select 1 from dual") { |r| nil } @active = true rescue @@ -319,7 +320,7 @@ class OCI8EnhancedAutoRecover < DelegateClass(OCI8) #:nodoc: end # Resets connection, by logging off and creating a new connection. - def reset! + def reset! #:nodoc: logoff rescue nil begin @connection = @factory.new_connection @config @@ -336,12 +337,12 @@ class OCI8EnhancedAutoRecover < DelegateClass(OCI8) #:nodoc: # ORA-03113: end-of-file on communication channel # ORA-03114: not connected to ORACLE # ORA-03135: connection lost contact - LOST_CONNECTION_ERROR_CODES = [ 28, 1012, 3113, 3114, 3135 ] + LOST_CONNECTION_ERROR_CODES = [ 28, 1012, 3113, 3114, 3135 ] #:nodoc: # Adds auto-recovery functionality. # # See: http://www.jiubao.org/ruby-oci8/api.en.html#label-11 - def exec(sql, *bindvars, &block) + def exec(sql, *bindvars, &block) #:nodoc: should_retry = self.class.auto_retry? && autocommit? begin @@ -356,11 +357,12 @@ class OCI8EnhancedAutoRecover < DelegateClass(OCI8) #:nodoc: end end - # RSI: otherwise not working in Ruby 1.9.1 + # otherwise not working in Ruby 1.9.1 if RUBY_VERSION =~ /^1\.9/ - def describe(name) + def describe(name) #:nodoc: @connection.describe(name) end end end +#:startdoc: lib/active_record/connection_adapters/oracle_enhanced_oci_connection.rb @@ -12,16 +12,42 @@ module ActiveRecord #:nodoc: module OracleEnhancedProcedures #:nodoc: module ClassMethods + # Specify custom create method which should be used instead of Rails generated INSERT statement. + # Provided block should return ID of new record. + # Example: + # 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 def set_create_method(&block) include_with_custom_methods self.custom_create_method = block end + # Specify custom update method which should be used instead of Rails generated UPDATE statement. + # Example: + # set_update_method do + # plsql.employees_pkg.update_employee( + # :p_employee_id => id, + # :p_first_name => first_name, + # :p_last_name => last_name + # ) + # end def set_update_method(&block) include_with_custom_methods self.custom_update_method = block end + # Specify custom delete method which should be used instead of Rails generated DELETE statement. + # Example: + # set_delete_method do + # plsql.employees_pkg.delete_employee( + # :p_employee_id => id + # ) + # end def set_delete_method(&block) include_with_custom_methods self.custom_delete_method = block @@ -35,7 +61,7 @@ module ActiveRecord #:nodoc: end end - module InstanceMethods + module InstanceMethods #:nodoc: def self.included(base) base.instance_eval do if private_instance_methods.include?('create_without_callbacks') || private_instance_methods.include?(:create_without_callbacks) lib/active_record/connection_adapters/oracle_enhanced_procedures.rb @@ -1,4 +1,4 @@ -# RSI: implementation idea taken from JDBC adapter +# implementation idea taken from JDBC adapter if defined?(Rake.application) && Rake.application && ActiveRecord::Base.configurations[RAILS_ENV]['adapter'] == 'oracle_enhanced' oracle_enhanced_rakefile = File.dirname(__FILE__) + "/oracle_enhanced.rake" if Rake.application.lookup("environment") lib/active_record/connection_adapters/oracle_enhanced_tasks.rb 9a5bd8fb733fdd41063ea437540b583d0de2a5a0 Raimonds Simanovskis raimonds.simanovskis@gmail.com http://github.com/rsim/oracle-enhanced/commit/669598232d27a46c22242cdc6f91722e3f2abb79 669598232d27a46c22242cdc6f91722e3f2abb79 2009-08-11T03:35:14-07:00 2009-08-11T03:35:14-07:00 reviewed and added comments to generate better RDoc documentation for API methods 3174985d3c99328e16ab980c1807be49eeb1c9d7 Raimonds Simanovskis raimonds.simanovskis@gmail.com