Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
executable file 1375 lines (1212 sloc) 62.4 KB
require 'yaml'
module ActiveRecord #:nodoc:
class ActiveRecordError < StandardError #:nodoc:
class SubclassNotFound < ActiveRecordError #:nodoc:
class AssociationTypeMismatch < ActiveRecordError #:nodoc:
class SerializationTypeMismatch < ActiveRecordError #:nodoc:
class AdapterNotSpecified < ActiveRecordError # :nodoc:
class AdapterNotFound < ActiveRecordError # :nodoc:
class ConnectionNotEstablished < ActiveRecordError #:nodoc:
class ConnectionFailed < ActiveRecordError #:nodoc:
class RecordNotFound < ActiveRecordError #:nodoc:
class StatementInvalid < ActiveRecordError #:nodoc:
class PreparedStatementInvalid < ActiveRecordError #:nodoc:
class StaleObjectError < ActiveRecordError #:nodoc:
class AttributeAssignmentError < ActiveRecordError #:nodoc:
attr_reader :exception, :attribute
def initialize(message, exception, attribute)
@exception = exception
@attribute = attribute
@message = message
class MultiparameterAssignmentErrors < ActiveRecordError #:nodoc:
attr_reader :errors
def initialize(errors)
@errors = errors
# Active Record objects doesn't specify their attributes directly, but rather infer them from the table definition with
# which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
# is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain
# database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.
# See the mapping rules in table_name and the full example in link:files/README.html for more insight.
# == Creation
# Active Records accepts constructor parameters either in a hash or as a block. The hash method is especially useful when
# you're receiving the data from somewhere else, like a HTTP request. It works like this:
# user ="name" => "David", "occupation" => "Code Artist")
# # => "David"
# You can also use block initialization:
# user = do |u|
# = "David"
# u.occupation = "Code Artist"
# end
# And of course you can just create a bare object and specify the attributes after the fact:
# user =
# = "David"
# user.occupation = "Code Artist"
# == Conditions
# Conditions can either be specified as a string or an array representing the WHERE-part of an SQL statement.
# The array form is to be used when the condition input is tainted and requires sanitization. The string form can
# be used for statements that doesn't involve tainted data. Examples:
# User < ActiveRecord::Base
# def self.authenticate_unsafely(user_name, password)
# find_first("user_name = '#{user_name}' AND password = '#{password}'")
# end
# def self.authenticate_safely(user_name, password)
# find_first([ "user_name = ? AND password = ?", user_name, password ])
# end
# end
# The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
# attacks if the <tt>user_name</tt> and +password+ parameters come directly from a HTTP request. The <tt>authenticate_safely</tt> method,
# on the other hand, will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query, which will ensure that
# an attacker can't escape the query and fake the login (or worse).
# == Overwriting default accessors
# All column values are automatically available through basic accessors on the Active Record object, but some times you
# want to specialize this behavior. This can be done by either by overwriting the default accessors (using the same
# name as the attribute) calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
# Example:
# class Song < ActiveRecord::Base
# # Uses an integer of seconds to hold the length of the song
# def length=(minutes)
# write_attribute("length", minutes * 60)
# end
# def length
# read_attribute("length") / 60
# end
# end
# == Accessing attributes before they have been type casted
# Some times you want to be able to read the raw attribute data without having the column-determined type cast run its course first.
# That can be done by using the <attribute>_before_type_cast accessors that all attributes have. For example, if your Account model
# has a balance attribute, you can call account.balance_before_type_cast or account.id_before_type_cast.
# This is especially useful in validation situations where the user might supply a string for an integer field and you want to display
# the original string back in an error message. Accessing the attribute normally would type cast the string to 0, which isn't what you
# want.
# == Dynamic attribute-based finders
# Dynamic attribute-based finders are a cleaner way of getting objects by simple queries without turning to SQL. They work by
# appending the name of an attribute to <tt>find_by_</tt>, so you get finders like <tt>Person.find_by_user_name, Payment.find_by_transaction_id</tt>.
# So instead of writing <tt>Person.find_first(["user_name = ?", user_name])</tt>, you just do <tt>Person.find_by_user_name(user_name)</tt>.
# It's also possible to use multiple attributes in the same find by separating them with "_and_", so you get finders like
# <tt>Person.find_by_user_name_and_password</tt> or even <tt>Payment.find_by_purchaser_and_state_and_country</tt>. So instead of writing
# <tt>Person.find_first(["user_name = ? AND password = ?", user_name, password])</tt>, you just do
# <tt>Person.find_by_user_name_and_password(user_name, password)</tt>.
# It's even possible to use all the additional parameters to find_first and find_all. For example, the full interface for Payment.find_all_by_amount
# is actually Payment.find_all_by_amount(amount, orderings = nil, limit = nil, joins = nil). And the full interface to Person.find_by_user_name is
# actually Person.find_by_user_name(user_name, orderings = nil)
# == Saving arrays, hashes, and other non-mappable objects in text columns
# Active Record can serialize any object in text columns using YAML. To do so, you must specify this with a call to the class method +serialize+.
# This makes it possible to store arrays, hashes, and other non-mappeable objects without doing any additional work. Example:
# class User < ActiveRecord::Base
# serialize :preferences
# end
# user = User.create("preferences" => { "background" => "black", "display" => large })
# User.find( # => { "background" => "black", "display" => large }
# You can also specify an class option as the second parameter that'll raise an exception if a serialized object is retrieved as a
# descendent of a class not in the hierarchy. Example:
# class User < ActiveRecord::Base
# serialize :preferences, Hash
# end
# user = User.create("preferences" => %w( one two three ))
# User.find( # raises SerializationTypeMismatch
# == Single table inheritance
# Active Record allows inheritance by storing the name of the class in a column that by default is called "type" (can be changed
# by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
# class Company < ActiveRecord::Base; end
# class Firm < Company; end
# class Client < Company; end
# class PriorityClient < Client; end
# When you do Firm.create("name" => "37signals"), this record will be saved in the companies table with type = "Firm". You can then
# fetch this row again using Company.find_first "name = '37signals'" and it will return a Firm object.
# If you don't have a type column defined in your table, single-table inheritance won't be triggered. In that case, it'll work just
# like normal subclasses with no special magic for differentiating between them or reloading the right type with find.
# Note, all the attributes for all the cases are kept in the same table. Read more:
# == Connection to multiple databases in different models
# Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
# All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
# For example, if Course is a ActiveRecord::Base, but resides in a different database you can just say Course.establish_connection
# and Course *and all its subclasses* will use this connection instead.
# This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
# requested, the retrieve_connection method will go up the class-hierarchy until a connection is found in the connection pool.
# == Exceptions
# * +ActiveRecordError+ -- generic error class and superclass of all other errors raised by Active Record
# * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include a
# <tt>:adapter</tt> key.
# * +AdapterNotSpecified+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified an non-existent adapter
# (or a bad spelling of an existing one).
# * +AssociationTypeMismatch+ -- the object assigned to the association wasn't of the type specified in the association definition.
# * +SerializationTypeMismatch+ -- the object serialized wasn't of the class specified as the second parameter.
# * +ConnectionNotEstablished+ -- no connection has been established. Use <tt>establish_connection</tt> before querying.
# * +RecordNotFound+ -- no record responded to the find* method.
# Either the row with the given ID doesn't exist or the row didn't meet the additional restrictions.
# * +StatementInvalid+ -- the database server rejected the SQL statement. The precise error is added in the message.
# Either the record with the given ID doesn't exist or the record didn't meet the additional restrictions.
# * +MultiparameterAssignmentErrors+ -- collection of errors that occurred during a mass assignment using the
# +attributes=+ method. The +errors+ property of this exception contains an array of +AttributeAssignmentError+
# objects that should be inspected to determine which attributes triggered the errors.
# * +AttributeAssignmentError+ -- an error occurred while doing a mass assignment through the +attributes=+ method.
# You can inspect the +attribute+ property of the exception object to determine which attribute triggered the error.
# *Note*: The attributes listed are class-level attributes (accessible from both the class and instance level).
# So it's possible to assign a logger to the class through Base.logger= which will then be used by all
# instances in the current object space.
class Base
include ClassInheritableAttributes
# Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed
# on to any new database connections made and which can be retrieved on both a class and instance level by calling +logger+.
cattr_accessor :logger
# Returns the connection currently associated with the class. This can
# also be used to "borrow" the connection to do database work unrelated
# to any of the specific Active Records.
def self.connection
# Returns the connection currently associated with the class. This can
# also be used to "borrow" the connection to do database work that isn't
# easily done without going straight to SQL.
def connection
def self.inherited(child) #:nodoc:
@@subclasses[self] ||= []
@@subclasses[self] << child
@@subclasses = {}
cattr_accessor :configurations
@@primary_key_prefix_type = {}
# Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
# :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
# the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
# that this is a global setting for all Active Records.
cattr_accessor :primary_key_prefix_type
@@primary_key_prefix_type = nil
# Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
# table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
# for tables in a shared database. By default, the prefix is the empty string.
cattr_accessor :table_name_prefix
@@table_name_prefix = ""
# Works like +table_name_prefix+, but appends instead of prepends (set to "_basecamp" gives "projects_basecamp",
# "people_basecamp"). By default, the suffix is the empty string.
cattr_accessor :table_name_suffix
@@table_name_suffix = ""
# Indicate whether or not table names should be the pluralized versions of the corresponding class names.
# If true, this the default table name for a +Product+ class will be +products+. If false, it would just be +product+.
# See table_name for the full rules on table/class naming. This is true, by default.
cattr_accessor :pluralize_table_names
@@pluralize_table_names = true
# Determines whether or not to use ANSI codes to colorize the logging statements committed by the connection adapter. These colors
# makes it much easier to overview things during debugging (when used through a reader like +tail+ and on a black background), but
# may complicate matters if you use software like syslog. This is true, by default.
cattr_accessor :colorize_logging
@@colorize_logging = true
# Determines whether to use Time.local (using :local) or Time.utc (using :utc) when pulling dates and times from the database.
# This is set to :local by default.
cattr_accessor :default_timezone
@@default_timezone = :local
class << self # Class methods
# Returns objects for the records responding to either a specific id (1), a list of ids (1, 5, 6) or an array of ids.
# If only one ID is specified, that object is returned directly. If more than one ID is specified, an array is returned.
# Examples:
# Person.find(1) # returns the object for ID = 1
# Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
# Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
# Person.find([1]) # returns an array for objects the object with ID = 1
# The last argument may be a Hash of find options. Currently, +conditions+ is the only option, behaving the same as with +find_all+.
# Person.find(1, :conditions => "associate_id = 5"
# Person.find(1, 2, 6, :conditions => "status = 'active'"
# Person.find([7, 17], :conditions => ["sanitize_me = ?", "bare'quote"]
# +RecordNotFound+ is raised if no record can be found.
def find(*args)
# Return an Array if ids are passed in an Array.
expects_array = args.first.kind_of?(Array)
# Extract options hash from argument list.
options = extract_options_from_args!(args)
conditions = " AND #{sanitize_sql(options[:conditions])}" if options[:conditions]
ids = args.flatten.compact.uniq
case ids.size
# Raise if no ids passed.
when 0
raise RecordNotFound, "Couldn't find #{name} without an ID#{conditions}"
# Find a single id.
when 1
unless result = find_first("#{primary_key} = #{sanitize(ids.first)}#{conditions}")
raise RecordNotFound, "Couldn't find #{name} with ID=#{ids.first}#{conditions}"
# Box result if expecting array.
expects_array ? [result] : result
# Find multiple ids.
ids_list = { |id| sanitize(id) }.join(',')
result = find_all("#{primary_key} IN (#{ids_list})#{conditions}", primary_key)
if result.size == ids.size
raise RecordNotFound, "Couldn't find all #{name.pluralize} with IDs (#{ids_list})#{conditions}"
# Returns true if the given +id+ represents the primary key of a record in the database, false otherwise.
# Example:
# Person.exists?(5)
def exists?(id)
!find_first("#{primary_key} = #{sanitize(id)}").nil?
# This method is deprecated in favor of find with the :conditions option.
# Works like find, but the record matching +id+ must also meet the +conditions+.
# +RecordNotFound+ is raised if no record can be found matching the +id+ or meeting the condition.
# Example:
# Person.find_on_conditions 5, "first_name LIKE '%dav%' AND last_name = 'heinemeier'"
def find_on_conditions(ids, conditions)
find(ids, :conditions => conditions)
# Returns an array of all the objects that could be instantiated from the associated
# table in the database. The +conditions+ can be used to narrow the selection of objects (WHERE-part),
# such as by "color = 'red'", and arrangement of the selection can be done through +orderings+ (ORDER BY-part),
# such as by "last_name, first_name DESC". A maximum of returned objects and their offset can be specified in
# +limit+ with either just a single integer as the limit or as an array with the first element as the limit,
# the second as the offset. Examples:
# Project.find_all "category = 'accounts'", "last_accessed DESC", 15
# Project.find_all ["category = ?", category_name], "created ASC", [15, 20]
def find_all(conditions = nil, orderings = nil, limit = nil, joins = nil)
sql = "SELECT * FROM #{table_name} "
sql << "#{joins} " if joins
add_conditions!(sql, conditions)
sql << "ORDER BY #{orderings} " unless orderings.nil?
limit = sanitize_sql(limit) if limit.is_a? Array and limit.first.is_a? String
connection.add_limit!(sql, limit) if limit
# Works like find_all, but requires a complete SQL string. Examples:
# Post.find_by_sql "SELECT p.*, FROM posts p, comments c WHERE = c.post_id"
# Post.find_by_sql ["SELECT * FROM posts WHERE author = ? AND created > ?", author_id, start_date]
def find_by_sql(sql)
connection.select_all(sanitize_sql(sql), "#{name} Load").inject([]) { |objects, record| objects << instantiate(record) }
# Returns the object for the first record responding to the conditions in +conditions+,
# such as "group = 'master'". If more than one record is returned from the query, it's the first that'll
# be used to create the object. In such cases, it might be beneficial to also specify
# +orderings+, like "income DESC, name", to control exactly which record is to be used. Example:
# Employee.find_first "income > 50000", "income DESC, name"
def find_first(conditions = nil, orderings = nil)
find_all(conditions, orderings, 1).first
# Creates an object, instantly saves it as a record (if the validation permits it), and returns it. If the save
# fail under validations, the unsaved object is still returned.
def create(attributes = nil)
if attributes.is_a?(Array)
attributes.collect { |attr| create(attr) }
object = new(attributes)
# Finds the record from the passed +id+, instantly saves it with the passed +attributes+ (if the validation permits it),
# and returns it. If the save fail under validations, the unsaved object is still returned.
def update(id, attributes)
if id.is_a?(Array)
idx = -1
id.collect { |id| idx += 1; update(id, attributes[idx]) }
object = find(id)
# Deletes the record with the given +id+ without instantiating an object first. If an array of ids is provided, all of them
# are deleted.
def delete(id)
delete_all([ "#{primary_key} IN (?)", id ])
# Destroys the record with the given +id+ by instantiating the object and calling #destroy (all the callbacks are the triggered).
# If an array of ids is provided, all of them are destroyed.
def destroy(id)
id.is_a?(Array) ? id.each { |id| destroy(id) } : find(id).destroy
# Updates all records with the SET-part of an SQL update statement in +updates+ and returns an integer with the number of rows updates.
# A subset of the records can be selected by specifying +conditions+. Example:
# Billing.update_all "category = 'authorized', approved = 1", "author = 'David'"
def update_all(updates, conditions = nil)
sql = "UPDATE #{table_name} SET #{sanitize_sql(updates)} "
add_conditions!(sql, conditions)
return connection.update(sql, "#{name} Update")
# Destroys the objects for all the records that matches the +condition+ by instantiating each object and calling
# the destroy method. Example:
# Person.destroy_all "last_login < '2004-04-04'"
def destroy_all(conditions = nil)
find_all(conditions).each { |object| object.destroy }
# Deletes all the records that matches the +condition+ without instantiating the objects first (and hence not
# calling the destroy method). Example:
# Post.destroy_all "person_id = 5 AND (category = 'Something' OR category = 'Else')"
def delete_all(conditions = nil)
sql = "DELETE FROM #{table_name} "
add_conditions!(sql, conditions)
connection.delete(sql, "#{name} Delete all")
# Returns the number of records that meets the +conditions+. Zero is returned if no records match. Example:
# Product.count "sales > 1"
def count(conditions = nil)
sql = "SELECT COUNT(*) FROM #{table_name} "
add_conditions!(sql, conditions)
# Returns the result of an SQL statement that should only include a COUNT(*) in the SELECT part.
# Product.count "SELECT COUNT(*) FROM sales s, customers c WHERE s.customer_id ="
def count_by_sql(sql)
sql = sanitize_conditions(sql)
count = connection.select_one(sql, "#{name} Count").values.first
return count ? count.to_i : 0
# Increments the specified counter by one. So <tt>DiscussionBoard.increment_counter("post_count",
# discussion_board_id)</tt> would increment the "post_count" counter on the board responding to discussion_board_id.
# This is used for caching aggregate values, so that they doesn't need to be computed every time. Especially important
# for looping over a collection where each element require a number of aggregate values. Like the DiscussionBoard
# that needs to list both the number of posts and comments.
def increment_counter(counter_name, id)
update_all "#{counter_name} = #{counter_name} + 1", "#{primary_key} = #{quote(id)}"
# Works like increment_counter, but decrements instead.
def decrement_counter(counter_name, id)
update_all "#{counter_name} = #{counter_name} - 1", "#{primary_key} = #{quote(id)}"
# Attributes named in this macro are protected from mass-assignment, such as <tt>new(attributes)</tt> and
# <tt>attributes=(attributes)</tt>. Their assignment will simply be ignored. Instead, you can use the direct writer
# methods to do assignment. This is meant to protect sensitive attributes to be overwritten by URL/form hackers. Example:
# class Customer < ActiveRecord::Base
# attr_protected :credit_rating
# end
# customer ="name" => David, "credit_rating" => "Excellent")
# customer.credit_rating # => nil
# customer.attributes = { "description" => "Jolly fellow", "credit_rating" => "Superb" }
# customer.credit_rating # => nil
# customer.credit_rating = "Average"
# customer.credit_rating # => "Average"
def attr_protected(*attributes)
write_inheritable_array("attr_protected", attributes)
# Returns an array of all the attributes that have been protected from mass-assignment.
def protected_attributes # :nodoc:
# If this macro is used, only those attributed named in it will be accessible for mass-assignment, such as
# <tt>new(attributes)</tt> and <tt>attributes=(attributes)</tt>. This is the more conservative choice for mass-assignment
# protection. If you'd rather start from an all-open default and restrict attributes as needed, have a look at
# attr_protected.
def attr_accessible(*attributes)
write_inheritable_array("attr_accessible", attributes)
# Returns an array of all the attributes that have been made accessible to mass-assignment.
def accessible_attributes # :nodoc:
# Specifies that the attribute by the name of +attr_name+ should be serialized before saving to the database and unserialized
# after loading from the database. The serialization is done through YAML. If +class_name+ is specified, the serialized
# object must be of that class on retrieval or +SerializationTypeMismatch+ will be raised.
def serialize(attr_name, class_name = Object)
write_inheritable_attribute("attr_serialized", serialized_attributes.update(attr_name.to_s => class_name))
# Returns a hash of all the attributes that have been specified for serialization as keys and their class restriction as values.
def serialized_attributes
read_inheritable_attribute("attr_serialized") || { }
# Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
# directly from ActiveRecord. So if the hierarchy looks like: Reply < Message < ActiveRecord, then Message is used
# to guess the table name from even when called on Reply. The rules used to do the guess are handled by the Inflector class
# in Active Support, which knows almost all common English inflections (report a bug if your inflection isn't covered).
# Additionally, the class-level table_name_prefix is prepended to the table_name and the table_name_suffix is appended.
# So if you have "myapp_" as a prefix, the table name guess for an Account class becomes "myapp_accounts".
# You can also overwrite this class method to allow for unguessable links, such as a Mouse class with a link to a
# "mice" table. Example:
# class Mouse < ActiveRecord::Base
# set_table_name "mice"
# end
def table_name
table_name_prefix + undecorated_table_name(class_name_of_active_record_descendant(self)) + table_name_suffix
# Defines the primary key field -- can be overridden in subclasses. Overwriting will negate any effect of the
# primary_key_prefix_type setting, though.
def primary_key
case primary_key_prefix_type
when :table_name
Inflector.foreign_key(class_name_of_active_record_descendant(self), false)
when :table_name_with_underscore
# Defines the column name for use with single table inheritance -- can be overridden in subclasses.
def inheritance_column
# Sets the table name to use to the given value, or (if the value
# is nil or false) to the value returned by the given block.
# Example:
# class Project < ActiveRecord::Base
# set_table_name "project"
# end
def set_table_name( value=nil, &block )
define_attr_method :table_name, value, &block
alias :table_name= :set_table_name
# Sets the name of the primary key column to use to the given value,
# or (if the value is nil or false) to the value returned by the given
# block.
# Example:
# class Project < ActiveRecord::Base
# set_primary_key "sysid"
# end
def set_primary_key( value=nil, &block )
define_attr_method :primary_key, value, &block
alias :primary_key= :set_primary_key
# Sets the name of the inheritance column to use to the given value,
# or (if the value # is nil or false) to the value returned by the
# given block.
# Example:
# class Project < ActiveRecord::Base
# set_inheritance_column do
# original_inheritance_column + "_id"
# end
# end
def set_inheritance_column( value=nil, &block )
define_attr_method :inheritance_column, value, &block
alias :inheritance_column= :set_inheritance_column
# Turns the +table_name+ back into a class name following the reverse rules of +table_name+.
def class_name(table_name = table_name) # :nodoc:
# remove any prefix and/or suffix from the table name
class_name = Inflector.camelize(table_name[table_name_prefix.length..-(table_name_suffix.length + 1)])
class_name = Inflector.singularize(class_name) if pluralize_table_names
return class_name
# Returns an array of column objects for the table associated with this class.
def columns
@columns ||= connection.columns(table_name, "#{name} Columns")
# Returns an array of column objects for the table associated with this class.
def columns_hash
@columns_hash ||= columns.inject({}) { |hash, column| hash[] = column; hash }
# Returns an array of columns objects where the primary id, all columns ending in "_id" or "_count",
# and columns used for single table inheritance has been removed.
def content_columns
@content_columns ||= columns.reject { |c| == primary_key || =~ /(_id|_count)$/ || == inheritance_column }
# Returns a hash of all the methods added to query each of the columns in the table with the name of the method as the key
# and true as the value. This makes it possible to do O(1) lookups in respond_to? to check if a given method for attribute
# is available.
def column_methods_hash
@dynamic_methods_hash ||= columns_hash.keys.inject( do |methods, attr|
methods[attr.to_sym] = true
methods["#{attr}=".to_sym] = true
methods["#{attr}?".to_sym] = true
methods["#{attr}_before_type_cast".to_sym] = true
# Resets all the cached information about columns, which will cause they to be reloaded on the next request.
def reset_column_information
@columns = @columns_hash = @content_columns = @dynamic_methods_hash = nil
def reset_column_information_and_inheritable_attributes_for_all_subclasses#:nodoc:
subclasses.each { |klass| klass.reset_inheritable_attributes; klass.reset_column_information }
# Transforms attribute key names into a more humane format, such as "First name" instead of "first_name". Example:
# Person.human_attribute_name("first_name") # => "First name"
# Deprecated in favor of just calling "first_name".humanize
def human_attribute_name(attribute_key_name) #:nodoc:
def descends_from_active_record? # :nodoc:
superclass == Base || !columns_hash.has_key?(inheritance_column)
def quote(object) #:nodoc:
# Used to sanitize objects before they're used in an SELECT SQL-statement. Delegates to <tt>connection.quote</tt>.
def sanitize(object) #:nodoc:
# Used to aggregate logging and benchmark, so you can measure and represent multiple statements in a single block.
# Usage (hides all the SQL calls for the individual actions and calculates total runtime for them all):
# Project.benchmark("Creating project") do
# project = Project.create("name" => "stuff")
# project.create_manager("name" => "David")
# project.milestones << Milestone.find_all
# end
def benchmark(title)
result = nil
bm = Benchmark.measure { result = silence { yield } } "#{title} (#{sprintf("%f", bm.real)})"
return result
# Silences the logger for the duration of the block.
def silence
result = nil
logger.level = Logger::ERROR
result = yield
logger.level = Logger::DEBUG
return result
# Overwrite the default class equality method to provide support for association proxies.
def ===(object)
# Finder methods must instantiate through this method to work with the single-table inheritance model
# that makes it possible to create objects of different types from the same table.
def instantiate(record)
object = record_with_type?(record) ? compute_type(record[inheritance_column]).allocate : allocate
rescue NameError
"The single-table inheritance mechanism failed to locate the subclass: '#{record[inheritance_column]}'. " +
"This error is raised because the column '#{inheritance_column}' is reserved for storing the class in case of inheritance. " +
"Please rename this column if you didn't intend it to be used for storing the inheritance class " +
"or overwrite #{self.to_s}.inheritance_column to use another column for that information."
object.instance_variable_set("@attributes", record)
return object
# Returns true if the +record+ has a single table inheritance column and is using it.
def record_with_type?(record)
record.include?(inheritance_column) && !record[inheritance_column].nil? &&
# Returns the name of the type of the record using the current module as a prefix. So descendents of
# MyApp::Business::Account would be appear as "MyApp::Business::AccountSubclass".
def type_name_with_module(type_name) =~ /::/ ?*)::/).first.first + "::" + type_name : type_name
# Adds a sanitized version of +conditions+ to the +sql+ string. Note that it's the passed +sql+ string is changed.
def add_conditions!(sql, conditions)
sql << "WHERE #{sanitize_sql(conditions)} " unless conditions.nil?
sql << (conditions.nil? ? "WHERE " : " AND ") + type_condition unless descends_from_active_record?
def type_condition
" (" + subclasses.inject("#{inheritance_column} = '#{Inflector.demodulize(name)}' ") do |condition, subclass|
condition << "OR #{inheritance_column} = '#{Inflector.demodulize(}' "
end + ") "
# Guesses the table name, but does not decorate it with prefix and suffix information.
def undecorated_table_name(class_name = class_name_of_active_record_descendant(self))
table_name = Inflector.underscore(Inflector.demodulize(class_name))
table_name = Inflector.pluralize(table_name) if pluralize_table_names
return table_name
# Enables dynamic finders like find_by_user_name(user_name) and find_by_user_name_and_password(user_name, password) that are turned into
# find_first(["user_name = ?", user_name]) and find_first(["user_name = ? AND password = ?", user_name, password]) respectively. Also works
# for find_all, but using find_all_by_amount(50) that are turned into find_all(["amount = ?", 50]).
# It's even possible to use all the additional parameters to find_first and find_all. For example, the full interface for find_all_by_amount
# is actually find_all_by_amount(amount, orderings = nil, limit = nil, joins = nil).
def method_missing(method_id, *arguments)
method_name = method_id.id2name
if method_name =~ /find_(all_by|by)_([_a-z][_a-z\d]*)/
finder, attributes = ($1 == "all_by" ? :find_all : :find_first), $2.split("_and_")
attributes.each { |attr_name| super unless column_methods_hash[attr_name.intern] }
attr_index = -1
conditions = attributes.collect { |attr_name| attr_index += 1; "#{attr_name} #{arguments[attr_index].nil? ? "IS" : "="} ? " }.join(" AND ")
send(finder, [conditions, *arguments[0...attributes.length]], *arguments[attributes.length..-1])
# Defines an "attribute" method (like #inheritance_column or
# #table_name). A new (class) method will be created with the
# given name. If a value is specified, the new method will
# return that value (as a string). Otherwise, the given block
# will be used to compute the value of the method.
# The original method will be aliased, with the new name being
# prefixed with "original_". This allows the new method to
# access the original value.
# Example:
# class A < ActiveRecord::Base
# define_attr_method :primary_key, "sysid"
# define_attr_method( :inheritance_column ) do
# original_inheritance_column + "_id"
# end
# end
def define_attr_method(name, value=nil, &block)
sing = class << self; self; end
block = proc { value.to_s } if value
sing.send( :alias_method, "original_#{name}", name )
sing.send( :define_method, name, &block )
def subclasses
@@subclasses[self] ||= []
@@subclasses[self] + extra = @@subclasses[self].inject([]) {|list, subclass| list + subclass.subclasses }
# Returns the class type of the record using the current module as a prefix. So descendents of
# MyApp::Business::Account would be appear as MyApp::Business::AccountSubclass.
def compute_type(type_name)
type_name_with_module(type_name).split("::").inject(Object) do |final_type, part|
final_type = final_type.const_get(part)
# Returns the name of the class descending directly from ActiveRecord in the inheritance hierarchy.
def class_name_of_active_record_descendant(klass)
if klass.superclass == Base
elsif klass.superclass.nil?
raise ActiveRecordError, "#{name} doesn't belong in a hierarchy descending from ActiveRecord"
# Accepts an array or string. The string is returned untouched, but the array has each value
# sanitized and interpolated into the sql statement.
# ["name='%s' and group_id='%s'", "foo'bar", 4] returns "name='foo''bar' and group_id='4'"
def sanitize_sql(ary)
return ary unless ary.is_a?(Array)
statement, *values = ary
if values.first.is_a?(Hash) and statement =~ /:\w+/
replace_named_bind_variables(statement, values.first)
elsif statement.include?('?')
replace_bind_variables(statement, values)
statement % values.collect { |value| connection.quote_string(value.to_s) }
alias_method :sanitize_conditions, :sanitize_sql
def replace_bind_variables(statement, values)
raise_if_bind_arity_mismatch(statement, statement.count('?'), values.size)
bound = values.dup
statement.gsub('?') { quote_bound_value(bound.shift) }
def replace_named_bind_variables(statement, bind_vars)
raise_if_bind_arity_mismatch(statement, statement.scan(/:(\w+)/).uniq.size, bind_vars.size)
statement.gsub(/:(\w+)/) do
match = $1.to_sym
if bind_vars.has_key?(match)
raise PreparedStatementInvalid, "missing value for :#{match} in #{statement}"
def quote_bound_value(value)
case value
when Array { |v| connection.quote(v) }.join(',')
def raise_if_bind_arity_mismatch(statement, expected, provided)
unless expected == provided
raise PreparedStatementInvalid, "wrong number of bind variables (#{provided} for #{expected}) in: #{statement}"
def extract_options_from_args!(args)
if args.last.is_a?(Hash) then args.pop else {} end
def encode_quoted_value(value)
quoted_value = connection.quote(value)
quoted_value = "'#{quoted_value[1..-2].gsub(/\'/, "\\\\'")}'" if quoted_value.include?("\\\'")
# New objects can be instantiated as either empty (pass no construction parameter) or pre-set with
# attributes but not yet saved (pass a hash with key names matching the associated table column names).
# In both instances, valid attribute keys are determined by the column names of the associated table --
# hence you can't have attributes that aren't part of the table columns.
def initialize(attributes = nil)
@attributes = attributes_from_column_definition
@new_record = true
self.attributes = attributes unless attributes.nil?
yield self if block_given?
# Every Active Record class must use "id" as their primary ID. This getter overwrites the native
# id method, which isn't being used in this context.
def id
# Enables Active Record objects to be used as URL parameters in Action Pack automatically.
alias_method :to_param, :id
def id_before_type_cast #:nodoc:
def quoted_id #:nodoc:
quote(id, self.class.columns_hash[self.class.primary_key])
# Sets the primary ID.
def id=(value)
write_attribute(self.class.primary_key, value)
# Returns true if this object hasn't been saved yet -- that is, a record for the object doesn't exist yet.
def new_record?
# * No record exists: Creates a new record with values matching those of the object attributes.
# * A record does exist: Updates the record with values matching those of the object attributes.
def save
# Deletes the record in the database and freezes this instance to reflect that no changes should
# be made (since they can't be persisted).
def destroy
unless new_record?
"DELETE FROM #{self.class.table_name} " +
"WHERE #{self.class.primary_key} = #{quote(id)}",
"#{} Destroy"
# Returns a clone of the record that hasn't been assigned an id yet and is treated as a new record.
def clone
attrs = self.attributes
cloned_record =
# Updates a single attribute and saves the record. This is especially useful for boolean flags on existing records.
# Note: This method is overwritten by the Validation module that'll make sure that updates made with this method
# doesn't get subjected to validation checks. Hence, attributes can be updated even if the full object isn't valid.
def update_attribute(name, value)
self[name] = value
# Updates all the attributes in from the passed hash and saves the record. If the object is invalid, the saving will
# fail and false will be returned.
def update_attributes(attributes)
self.attributes = attributes
return save
# Initializes the +attribute+ to zero if nil and adds one. Only makes sense for number-based attributes. Returns self.
def increment(attribute)
self[attribute] ||= 0
self[attribute] += 1
# Increments the +attribute+ and saves the record.
def increment!(attribute)
increment(attribute).update_attribute(attribute, self[attribute])
# Initializes the +attribute+ to zero if nil and subtracts one. Only makes sense for number-based attributes. Returns self.
def decrement(attribute)
self[attribute] ||= 0
self[attribute] -= 1
# Decrements the +attribute+ and saves the record.
def decrement!(attribute)
decrement(attribute).update_attribute(attribute, self[attribute])
# Turns an +attribute+ that's currently true into false and vice versa. Returns self.
def toggle(attribute)
self[attribute] = quote(!send("#{attribute}?", column_for_attribute(attribute)))
# Toggles the +attribute+ and saves the record.
def toggle!(attribute)
toggle(attribute).update_attribute(attribute, self[attribute])
# Reloads the attributes of this object from the database.
def reload
return self
# Returns the value of attribute identified by <tt>attr_name</tt> after it has been type cast (for example,
# "2004-12-12" in a data column is cast to a date object, like, 12, 12)).
# (Alias for the protected read_attribute method).
def [](attr_name)
# Updates the attribute identified by <tt>attr_name</tt> with the specified +value+.
# (Alias for the protected write_attribute method).
def []= (attr_name, value)
write_attribute(attr_name.to_s, value)
# Allows you to set all the attributes at once by passing in a hash with keys
# matching the attribute names (which again matches the column names). Sensitive attributes can be protected
# from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively
# specify which attributes *can* be accessed in with the +attr_accessible+ macro. Then all the
# attributes not included in that won't be allowed to be mass-assigned.
def attributes=(attributes)
return if attributes.nil?
multi_parameter_attributes = []
remove_attributes_protected_from_mass_assignment(attributes).each do |k, v|
k.include?("(") ? multi_parameter_attributes << [ k, v ] : send(k + "=", v)
# Returns a hash of all the attributes with their names as keys and clones of their objects as values.
def attributes
self.attribute_names.inject({}) do |attributes, name|
attributes[name] = read_attribute(name).clone
rescue TypeError
attributes[name] = read_attribute(name)
# Returns true if the specified +attribute+ has been set by the user or by a database load and is neither
# nil nor empty? (the latter only applies to objects that responds to empty?, most notably Strings).
def attribute_present?(attribute)
is_empty = read_attribute(attribute).respond_to?("empty?") ? read_attribute(attribute).empty? : false
@attributes.include?(attribute) && !@attributes[attribute].nil? && !is_empty
# Returns an array of names for the attributes available on this object sorted alphabetically.
def attribute_names
# Returns the column object for the named attribute.
def column_for_attribute(name)
# Returns true if the +comparison_object+ is the same object, or is of the same type and has the same id.
def ==(comparison_object)
comparison_object.equal?(self) or (comparison_object.instance_of?(self.class) and == id)
# Delegates to ==
def eql?(comparison_object)
self == (comparison_object)
# Delegates to id in order to allow two records of the same type and id to work with something like:
# [ Person.find(1), Person.find(2), Person.find(3) ] & [ Person.find(1), Person.find(4) ] # => [ Person.find(1) ]
def hash
# For checking respond_to? without searching the attributes (which is faster).
alias_method :respond_to_without_attributes?, :respond_to?
# A Person object with a name attribute can ask person.respond_to?("name"), person.respond_to?("name="), and
# person.respond_to?("name?") which will all return true.
def respond_to?(method, include_priv = false)
self.class.column_methods_hash[method.to_sym] || respond_to_without_attributes?(method, include_priv)
def create_or_update
if new_record? then create else update end
return true
# Updates the associated record with values matching those of the instant attributes.
def update
"UPDATE #{self.class.table_name} " +
"SET #{quoted_comma_pair_list(connection, attributes_with_quotes(false))} " +
"WHERE #{self.class.primary_key} = #{quote(id)}",
"#{} Update"
# Creates a new record with values matching those of the instant attributes.
def create = connection.insert(
"INSERT INTO #{self.class.table_name} " +
"(#{quoted_column_names.join(', ')}) " +
"VALUES(#{attributes_with_quotes.values.join(', ')})",
"#{} Create",
@new_record = false
# Sets the attribute used for single table inheritance to this class name if this is not the ActiveRecord descendant.
# Considering the hierarchy Reply < Message < ActiveRecord, this makes it possible to do without having to
# set Reply[Reply.inheritance_column] = "Reply" yourself. No such attribute would be set for objects of the
# Message class in that example.
def ensure_proper_type
unless self.class.descends_from_active_record?
write_attribute(self.class.inheritance_column, Inflector.demodulize(
# Allows access to the object attributes, which are held in the @attributes hash, as were
# they first-class methods. So a Person class with a name attribute can use Person#name and
# Person#name= and never directly use the attributes hash -- except for multiple assigns with
# ActiveRecord#attributes=. A Milestone class can also ask Milestone#completed? to test that
# the completed attribute is not nil or 0.
# It's also possible to instantiate related objects, so a Client class belonging to the clients
# table with a master_id foreign key can instantiate master through Client#master.
def method_missing(method_id, *arguments)
method_name = method_id.id2name
if method_name =~ read_method? && @attributes.include?($1)
return read_attribute($1)
elsif method_name =~ read_untyped_method? && @attributes.include?($1)
return read_attribute_before_type_cast($1)
elsif method_name =~ write_method? && @attributes.include?($1)
write_attribute($1, arguments[0])
elsif method_name =~ query_method? && @attributes.include?($1)
return query_attribute($1)
def read_method?() /^([a-zA-Z][-_\w]*)[^=?]*$/ end
def read_untyped_method?() /^([a-zA-Z][-_\w]*)_before_type_cast$/ end
def write_method?() /^([a-zA-Z][-_\w]*)=.*$/ end
def query_method?() /^([a-zA-Z][-_\w]*)\?$/ end
# Returns the value of attribute identified by <tt>attr_name</tt> after it has been type cast (for example,
# "2004-12-12" in a data column is cast to a date object, like, 12, 12)).
def read_attribute(attr_name)
if @attributes.keys.include? attr_name
if column = column_for_attribute(attr_name)
unserializable_attribute?(attr_name, column) ?
unserialize_attribute(attr_name) : column.type_cast(@attributes[attr_name])
def read_attribute_before_type_cast(attr_name)
# Returns true if the attribute is of a text column and marked for serialization.
def unserializable_attribute?(attr_name, column)
@attributes[attr_name] && [:text, :string].include?(column.send(:type)) && @attributes[attr_name].is_a?(String) && self.class.serialized_attributes[attr_name]
# Returns the unserialized object of the attribute.
def unserialize_attribute(attr_name)
unserialized_object = object_from_yaml(@attributes[attr_name])
if unserialized_object.is_a?(self.class.serialized_attributes[attr_name])
@attributes[attr_name] = unserialized_object
"#{attr_name} was supposed to be a #{self.class.serialized_attributes[attr_name]}, " +
"but was a #{unserialized_object.class.to_s}"
# Updates the attribute identified by <tt>attr_name</tt> with the specified +value+. Empty strings for fixnum and float
# columns are turned into nil.
def write_attribute(attr_name, value)
@attributes[attr_name] = empty_string_for_number_column?(attr_name, value) ? nil : value
def empty_string_for_number_column?(attr_name, value)
column = column_for_attribute(attr_name)
column && (column.klass == Fixnum || column.klass == Float) && value == ""
def query_attribute(attr_name)
attribute = @attributes[attr_name]
if attribute.kind_of?(Fixnum) && attribute == 0
elsif attribute.kind_of?(String) && attribute == "0"
elsif attribute.kind_of?(String) && attribute.empty?
elsif attribute.nil?
elsif attribute == false
elsif attribute == "f"
elsif attribute == "false"
def remove_attributes_protected_from_mass_assignment(attributes)
if self.class.accessible_attributes.nil? && self.class.protected_attributes.nil?
attributes.reject { |key, value| attributes_protected_by_default.include?(key) }
elsif self.class.protected_attributes.nil?
attributes.reject { |key, value| !self.class.accessible_attributes.include?(key.intern) || attributes_protected_by_default.include?(key) }
elsif self.class.accessible_attributes.nil?
attributes.reject { |key, value| self.class.protected_attributes.include?(key.intern) || attributes_protected_by_default.include?(key) }
# The primary key and inheritance column can never be set by mass-assignment for security reasons.
def attributes_protected_by_default
[ self.class.primary_key, self.class.inheritance_column ]
# Returns copy of the attributes hash where all the values have been safely quoted for use in
# an SQL statement.
def attributes_with_quotes(include_primary_key = true)
columns_hash = self.class.columns_hash
attrs_quoted = attributes.inject({}) do |attrs_quoted, pair|
attrs_quoted[pair.first] = quote(pair.last, columns_hash[pair.first]) unless !include_primary_key && pair.first == self.class.primary_key
attrs_quoted.delete_if { |key, value| !self.class.columns_hash.keys.include?(key) }
# Quote strings appropriately for SQL statements.
def quote(value, column = nil)
connection.quote(value, column)
# Interpolate custom sql string in instance context.
# Optional record argument is meant for custom insert_sql.
def interpolate_sql(sql, record = nil)
# Initializes the attributes array with keys matching the columns from the linked table and
# the values matching the corresponding default value of that column, so
# that a new instance, or one populated from a passed-in Hash, still has all the attributes
# that instances loaded from the database would.
def attributes_from_column_definition
connection.columns(self.class.table_name, "#{} Columns").inject({}) do |attributes, column|
attributes[] = column.default unless == self.class.primary_key
# Instantiates objects for all attribute classes that needs more than one constructor parameter. This is done
# by calling new on the column type or aggregation type (through composed_of) object with these parameters.
# So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
# written_on (a date type) with"2004", "6", "24"). You can also specify a typecast character in the
# parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
# s for String, and a for Array. If all the values for a given attribute is empty, the attribute will be set to nil.
def assign_multiparameter_attributes(pairs)
# Includes an ugly hack for Time.local instead of because the latter is reserved by Time itself.
def execute_callstack_for_multiparameter_attributes(callstack)
errors = []
callstack.each do |name, values|
klass = (self.class.reflect_on_aggregation(name) || column_for_attribute(name)).klass
if values.empty?
send(name + "=", nil)
send(name + "=", Time == klass ? klass.local(*values) :*values))
rescue => ex
errors <<"error on assignment #{values.inspect} to #{name}", ex, name)
unless errors.empty?
raise, "#{errors.size} error(s) on assignment of multiparameter attributes"
def extract_callstack_for_multiparameter_attributes(pairs)
attributes = { }
for pair in pairs
multiparameter_name, value = pair
attribute_name = multiparameter_name.split("(").first
attributes[attribute_name] = [] unless attributes.include?(attribute_name)
unless value.empty?
attributes[attribute_name] <<
[ find_parameter_position(multiparameter_name), type_cast_attribute_value(multiparameter_name, value) ]
attributes.each { |name, values| attributes[name] = values.sort_by{ |v| v.first }.collect { |v| v.last } }
def type_cast_attribute_value(multiparameter_name, value)
multiparameter_name =~ /\([0-9]*([a-z])\)/ ? value.send("to_" + $1) : value
def find_parameter_position(multiparameter_name)
# Returns a comma-separated pair list, like "key1 = val1, key2 = val2".
def comma_pair_list(hash)
hash.inject([]) { |list, pair| list << "#{pair.first} = #{pair.last}" }.join(", ")
def quoted_column_names(attributes = attributes_with_quotes)
attributes.keys.collect { |column_name| connection.quote_column_name(column_name) }
def quote_columns(column_quoter, hash)
hash.inject({}) do |list, pair|
list[column_quoter.quote_column_name(pair.first)] = pair.last
def quoted_comma_pair_list(column_quoter, hash)
comma_pair_list(quote_columns(column_quoter, hash))
def object_from_yaml(string)
return string unless string.is_a?(String)
if has_yaml_encoding_header?(string)
rescue Object
# Apparently wasn't YAML anyway
def has_yaml_encoding_header?(string)
string[0..3] == "--- "
Jump to Line
Something went wrong with that request. Please try again.