1 = Active Record -- Object-relation mapping put on rails
3 Active Record connects business objects and database tables to create a persistable
4 domain model where logic and data are presented in one wrapping. It's an implementation
5 of the object-relational mapping (ORM) pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html]
6 by the same name as described by Martin Fowler:
8 "An object that wraps a row in a database table or view, encapsulates
9 the database access, and adds domain logic on that data."
11 Active Record's main contribution to the pattern is to relieve the original of two stunting problems:
12 lack of associations and inheritance. By adding a simple domain language-like set of macros to describe
13 the former and integrating the Single Table Inheritance pattern for the latter, Active Record narrows the
14 gap of functionality between the data mapper and active record approach.
16 A short rundown of the major features:
18 * Automated mapping between classes and tables, attributes and columns.
20 class Product < ActiveRecord::Base; end
22 ...is automatically mapped to the table named "products", such as:
24 CREATE TABLE products (
25 id int(11) NOT NULL auto_increment,
30 ...which again gives Product#name and Product#name=(new_name)
32 {Learn more}[link:classes/ActiveRecord/Base.html]
35 * Associations between objects controlled by simple meta-programming macros.
37 class Firm < ActiveRecord::Base
40 belongs_to :conglomorate
43 {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
46 * Aggregations of value objects controlled by simple meta-programming macros.
48 class Account < ActiveRecord::Base
49 composed_of :balance, :class_name => "Money",
50 :mapping => %w(balance amount)
52 :mapping => [%w(address_street street), %w(address_city city)]
55 {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
58 * Validation rules that can differ for new or existing objects.
60 class Account < ActiveRecord::Base
61 validates_presence_of :subdomain, :name, :email_address, :password
62 validates_uniqueness_of :subdomain
63 validates_acceptance_of :terms_of_service, :on => :create
64 validates_confirmation_of :password, :email_address, :on => :create
67 {Learn more}[link:classes/ActiveRecord/Validations.html]
69 * Callbacks as methods or queues on the entire lifecycle (instantiation, saving, destroying, validating, etc).
71 class Person < ActiveRecord::Base
72 def before_destroy # is called just before Person#destroy
73 CreditCard.find(credit_card_id).destroy
77 class Account < ActiveRecord::Base
78 after_find :eager_load, 'self.class.announce(#{id})'
81 {Learn more}[link:classes/ActiveRecord/Callbacks.html]
84 * Observers for the entire lifecycle
86 class CommentObserver < ActiveRecord::Observer
87 def after_create(comment) # is called just after Comment#save
88 Notifications.deliver_new_comment("david@loudthinking.com", comment)
92 {Learn more}[link:classes/ActiveRecord/Observer.html]
95 * Inheritance hierarchies
97 class Company < ActiveRecord::Base; end
98 class Firm < Company; end
99 class Client < Company; end
100 class PriorityClient < Client; end
102 {Learn more}[link:classes/ActiveRecord/Base.html]
107 # Database transaction
108 Account.transaction do
109 david.withdrawal(100)
113 {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
116 * Reflections on columns, associations, and aggregations
118 reflection = Firm.reflect_on_association(:clients)
119 reflection.klass # => Client (class)
120 Firm.columns # Returns an array of column descriptors for the firms table
122 {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
125 * Direct manipulation (instead of service invocation)
127 So instead of (Hibernate[http://www.hibernate.org/] example):
130 DomesticCat pk = (DomesticCat) sess.load( Cat.class, new Long(pkId) );
131 // something interesting involving a cat...
133 sess.flush(); // force the SQL INSERT
135 Active Record lets you:
139 # something even more interesting involving the same cat...
142 {Learn more}[link:classes/ActiveRecord/Base.html]
145 * Database abstraction through simple adapters (~100 lines) with a shared connector
147 ActiveRecord::Base.establish_connection(:adapter => "sqlite", :database => "dbfile")
149 ActiveRecord::Base.establish_connection(
151 :host => "localhost",
153 :password => "secret",
154 :database => "activerecord"
157 {Learn more}[link:classes/ActiveRecord/Base.html#M000081] and read about the built-in support for
158 MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html], PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], SQLite[link:classes/ActiveRecord/ConnectionAdapters/SQLiteAdapter.html], Oracle[link:classes/ActiveRecord/ConnectionAdapters/OracleAdapter.html], SQLServer[link:classes/ActiveRecord/ConnectionAdapters/SQLServerAdapter.html], and DB2[link:classes/ActiveRecord/ConnectionAdapters/DB2Adapter.html].
161 * Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]
163 ActiveRecord::Base.logger = Logger.new(STDOUT)
164 ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
167 * Database agnostic schema management with Migrations
169 class AddSystemSettings < ActiveRecord::Migration
171 create_table :system_settings do |t|
179 SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
183 drop_table :system_settings
187 {Learn more}[link:classes/ActiveRecord/Migration.html]
189 == Simple example (1/2): Defining tables and classes (using MySQL)
191 Data definitions are specified only in the database. Active Record queries the database for
192 the column names (that then serves to determine which attributes are valid) on regular
193 object instantiation through the new constructor and relies on the column names in the rows
196 # CREATE TABLE companies (
197 # id int(11) unsigned NOT NULL auto_increment,
204 Active Record automatically links the "Company" object to the "companies" table
206 class Company < ActiveRecord::Base
207 has_many :people, :class_name => "Person"
213 def people_with_all_clients
214 clients.inject([]) { |people, client| people + client.people }
218 The foreign_key is only necessary because we didn't use "firm_id" in the data definition
220 class Client < Company
221 belongs_to :firm, :foreign_key => "client_of"
224 # CREATE TABLE people (
225 # id int(11) unsigned NOT NULL auto_increment,
231 Active Record will also automatically link the "Person" object to the "people" table
233 class Person < ActiveRecord::Base
237 == Simple example (2/2): Using the domain
239 Picking a database connection for all the Active Records
241 ActiveRecord::Base.establish_connection(
243 :host => "localhost",
245 :password => "secret",
246 :database => "activerecord"
251 firm = Firm.new("name" => "Next Angle")
252 # SQL: INSERT INTO companies (name, type) VALUES("Next Angle", "Firm")
255 client = Client.new("name" => "37signals", "client_of" => firm.id)
256 # SQL: INSERT INTO companies (name, client_of, type) VALUES("37signals", 1, "Firm")
259 Lots of different finders
261 # SQL: SELECT * FROM companies WHERE id = 1
262 next_angle = Company.find(1)
264 # SQL: SELECT * FROM companies WHERE id = 1 AND type = 'Firm'
265 next_angle = Firm.find(1)
267 # SQL: SELECT * FROM companies WHERE id = 1 AND name = 'Next Angle'
268 next_angle = Company.find(:first, :conditions => "name = 'Next Angle'")
270 next_angle = Firm.find_by_sql("SELECT * FROM companies WHERE id = 1").first
272 The supertype, Company, will return subtype instances
276 All the dynamic methods added by the has_many macro
278 next_angle.clients.empty? # true
279 next_angle.clients.size # total number of clients
280 all_clients = next_angle.clients
282 Constrained finds makes access security easier when ID comes from a web-app
284 # SQL: SELECT * FROM companies WHERE client_of = 1 AND type = 'Client' AND id = 2
285 thirty_seven_signals = next_angle.clients.find(2)
287 Bi-directional associations thanks to the "belongs_to" macro
289 thirty_seven_signals.firm.nil? # true
294 Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is
295 object-relational mapping. The prime directive for this mapping has been to minimize
296 the amount of code needed to build a real-world domain model. This is made possible
297 by relying on a number of conventions that make it easy for Active Record to infer
298 complex relations and structures from a minimal amount of explicit direction.
300 Convention over Configuration:
302 * Lots of reflection and run-time extension
303 * Magic is not inherently a bad word
306 * Lets you drop down to SQL for odd cases and performance
307 * Doesn't attempt to duplicate or replace data definitions
312 The latest version of Active Record can be found at
314 * http://rubyforge.org/project/showfiles.php?group_id=182
316 Documentation can be found at
318 * http://ar.rubyonrails.com
323 The prefered method of installing Active Record is through its GEM file. You'll need to have
324 RubyGems[http://rubygems.rubyforge.org/wiki/wiki.pl] installed for that, though. If you have,
327 % [sudo] gem install activerecord-1.10.0.gem
329 You can also install Active Record the old-fashioned way with the following command:
331 % [sudo] ruby install.rb
333 from its distribution directory.
338 Active Record is released under the MIT license.
343 The Active Record homepage is http://www.rubyonrails.com. You can find the Active Record
344 RubyForge page at http://rubyforge.org/projects/activerecord. And as Jim from Rake says:
346 Feel free to submit commits or feature requests. If you send a patch,
347 remember to update the corresponding unit tests. If fact, I prefer
348 new feature to be submitted in the form of new unit tests.
350 For other information, feel free to ask on the rubyonrails-talk
351 (http://groups.google.com/group/rubyonrails-talk) mailing list.