Skip to content
Newer
Older
100644 223 lines (145 sloc) 6.76 KB
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
1 = Active Record -- Object-relational mapping put on rails
db045db @dhh Initial
dhh authored Nov 24, 2004
2
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
3 Active Record connects classes to relational database tables to establish an
4 almost zero-configuration persistence layer for applications. The library
5 provides a base class that, when subclassed, sets up a mapping between the new
6 class and an existing table in the database. In context of an application,
7 these classes are commonly referred to as *models*. Models can also be
8 connected to other models; this is done by defining *associations*.
db045db @dhh Initial
dhh authored Nov 24, 2004
9
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
10 Active Record relies heavily on naming in that it uses class and association
11 names to establish mappings between respective database tables and foreign key
12 columns. Although these mappings can be defined explicitly, it's recommended
13 to follow naming conventions, especially when getting started with the
14 library.
db045db @dhh Initial
dhh authored Nov 24, 2004
15
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
16 A short rundown of some of the major features:
db045db @dhh Initial
dhh authored Nov 24, 2004
17
18 * Automated mapping between classes and tables, attributes and columns.
19
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
20 class Product < ActiveRecord::Base
21 end
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
22
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
23 The Product class is automatically mapped to the table named "products",
24 which might look like this:
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
25
db045db @dhh Initial
dhh authored Nov 24, 2004
26 CREATE TABLE products (
27 id int(11) NOT NULL auto_increment,
28 name varchar(255),
29 PRIMARY KEY (id)
30 );
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
31
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
32 This would also define the following accessors: `Product#name` and
33 `Product#name=(new_name)`
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
34
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
35 {Learn more}[link:classes/ActiveRecord/Base.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
36
37
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
38 * Associations between objects defined by simple class methods.
db045db @dhh Initial
dhh authored Nov 24, 2004
39
40 class Firm < ActiveRecord::Base
41 has_many :clients
42 has_one :account
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
43 belongs_to :conglomerate
db045db @dhh Initial
dhh authored Nov 24, 2004
44 end
45
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
46 {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
47
48
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
49 * Aggregations of value objects.
db045db @dhh Initial
dhh authored Nov 24, 2004
50
51 class Account < ActiveRecord::Base
52 composed_of :balance, :class_name => "Money",
53 :mapping => %w(balance amount)
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
54 composed_of :address,
db045db @dhh Initial
dhh authored Nov 24, 2004
55 :mapping => [%w(address_street street), %w(address_city city)]
56 end
57
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
58 {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
59
60
61 * Validation rules that can differ for new or existing objects.
62
6860db6 @dhh Renamed Mixins to Acts to resemble the change from include ActiveReco…
dhh authored Dec 16, 2004
63 class Account < ActiveRecord::Base
64 validates_presence_of :subdomain, :name, :email_address, :password
65 validates_uniqueness_of :subdomain
66 validates_acceptance_of :terms_of_service, :on => :create
67 validates_confirmation_of :password, :email_address, :on => :create
68 end
db045db @dhh Initial
dhh authored Nov 24, 2004
69
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
70 {Learn more}[link:classes/ActiveRecord/Validations.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
71
72
5430f5b @jaimeiniesta lifecycle should be two words, life cycle
jaimeiniesta authored Aug 26, 2010
73 * Callbacks available for the entire life cycle (instantiation, saving, destroying, validating, etc.)
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
74
75 class Person < ActiveRecord::Base
76 before_destroy :invalidate_payment_plan
77 # the `invalidate_payment_plan` method gets called just before Person#destroy
db045db @dhh Initial
dhh authored Nov 24, 2004
78 end
79
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
80 {Learn more}[link:classes/ActiveRecord/Callbacks.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
81
82
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
83 * Observers that react to changes in a model
db045db @dhh Initial
dhh authored Nov 24, 2004
84
85 class CommentObserver < ActiveRecord::Observer
86 def after_create(comment) # is called just after Comment#save
23ad13e @guilleiguaran Mailer example has more sense calling to deliver method
guilleiguaran authored May 15, 2011
87 CommentMailer.new_comment_email("david@loudthinking.com", comment).deliver
db045db @dhh Initial
dhh authored Nov 24, 2004
88 end
89 end
90
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
91 {Learn more}[link:classes/ActiveRecord/Observer.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
92
93
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
94 * Inheritance hierarchies
db045db @dhh Initial
dhh authored Nov 24, 2004
95
96 class Company < ActiveRecord::Base; end
97 class Firm < Company; end
98 class Client < Company; end
99 class PriorityClient < Client; end
100
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
101 {Learn more}[link:classes/ActiveRecord/Base.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
102
103
aa4af60 @lifo Improve documentation.
lifo authored Apr 5, 2008
104 * Transactions
db045db @dhh Initial
dhh authored Nov 24, 2004
105
aa4af60 @lifo Improve documentation.
lifo authored Apr 5, 2008
106 # Database transaction
db045db @dhh Initial
dhh authored Nov 24, 2004
107 Account.transaction do
108 david.withdrawal(100)
109 mary.deposit(100)
110 end
111
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
112 {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
113
114
115 * Reflections on columns, associations, and aggregations
116
117 reflection = Firm.reflect_on_association(:clients)
118 reflection.klass # => Client (class)
119 Firm.columns # Returns an array of column descriptors for the firms table
120
c4e5196 @dhh Updated documentation even more
dhh authored Feb 23, 2005
121 {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
db045db @dhh Initial
dhh authored Nov 24, 2004
122
123
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
124 * Database abstraction through simple adapters
db045db @dhh Initial
dhh authored Nov 24, 2004
125
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
126 # connect to SQLite3
127 ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "dbfile.sqlite3")
db045db @dhh Initial
dhh authored Nov 24, 2004
128
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
129 # connect to MySQL with authentication
130 ActiveRecord::Base.establish_connection(
3145c8a @vijaydev changes in examples - reflect new mailer api and mysql2 adapter
vijaydev authored Dec 18, 2010
131 :adapter => "mysql2",
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
132 :host => "localhost",
133 :username => "me",
134 :password => "secret",
135 :database => "activerecord"
136 )
db045db @dhh Initial
dhh authored Nov 24, 2004
137
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
138 {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for
139 MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html],
140 PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], and
141 SQLite3[link:classes/ActiveRecord/ConnectionAdapters/SQLite3Adapter.html].
db045db @dhh Initial
dhh authored Nov 24, 2004
142
143
144 * Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]
145
146 ActiveRecord::Base.logger = Logger.new(STDOUT)
147 ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
148
149
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored May 3, 2008
150 * Database agnostic schema management with Migrations
151
152 class AddSystemSettings < ActiveRecord::Migration
153 def self.up
154 create_table :system_settings do |t|
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
155 t.string :name
156 t.string :label
157 t.text :value
158 t.string :type
159 t.integer :position
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored May 3, 2008
160 end
161
162 SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
163 end
164
165 def self.down
166 drop_table :system_settings
167 end
168 end
169
170 {Learn more}[link:classes/ActiveRecord/Migration.html]
171
db045db @dhh Initial
dhh authored Nov 24, 2004
172
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
173 == Philosophy
db045db @dhh Initial
dhh authored Nov 24, 2004
174
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
175 Active Record is an implementation of the object-relational mapping (ORM)
176 pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html] by the same
177 name described by Martin Fowler:
db045db @dhh Initial
dhh authored Nov 24, 2004
178
d5ee17e @mislav improve Active Record README
mislav authored Jul 19, 2010
179 "An object that wraps a row in a database table or view,
180 encapsulates the database access, and adds domain logic on that data."
db045db @dhh Initial
dhh authored Nov 24, 2004
181
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
182 Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is
db045db @dhh Initial
dhh authored Nov 24, 2004
183 object-relational mapping. The prime directive for this mapping has been to minimize
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored Nov 7, 2005
184 the amount of code needed to build a real-world domain model. This is made possible
db045db @dhh Initial
dhh authored Nov 24, 2004
185 by relying on a number of conventions that make it easy for Active Record to infer
186 complex relations and structures from a minimal amount of explicit direction.
187
188 Convention over Configuration:
189 * No XML-files!
190 * Lots of reflection and run-time extension
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored Aug 14, 2010
191 * Magic is not inherently a bad word
db045db @dhh Initial
dhh authored Nov 24, 2004
192
193 Admit the Database:
194 * Lets you drop down to SQL for odd cases and performance
195 * Doesn't attempt to duplicate or replace data definitions
196
197
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
198 == Download and installation
db045db @dhh Initial
dhh authored Nov 24, 2004
199
f1082bd @josevalim Remove old install.rb files.
josevalim authored Jul 21, 2010
200 The latest version of Active Record can be installed with Rubygems:
db045db @dhh Initial
dhh authored Nov 24, 2004
201
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
202 % [sudo] gem install activerecord
db045db @dhh Initial
dhh authored Nov 24, 2004
203
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
204 Source code can be downloaded as part of the Rails project on GitHub
db045db @dhh Initial
dhh authored Nov 24, 2004
205
5bed377 @amatsuda "SSL everywhere" for GitHub URLs
amatsuda authored Mar 7, 2011
206 * https://github.com/rails/rails/tree/master/activerecord/
db045db @dhh Initial
dhh authored Nov 24, 2004
207
208
209 == License
210
b3bfe13 @dhh Updated the license (still referered to the old ruby one)
dhh authored Feb 24, 2005
211 Active Record is released under the MIT license.
db045db @dhh Initial
dhh authored Nov 24, 2004
212
213
214 == Support
215
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
216 API documentation is at
db045db @dhh Initial
dhh authored Nov 24, 2004
217
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
218 * http://api.rubyonrails.com
db045db @dhh Initial
dhh authored Nov 24, 2004
219
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored Jul 18, 2010
220 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
221
9870afb @arunagw Some readme fixes as required.
arunagw authored May 10, 2011
222 * https://github.com/rails/rails/issues
Something went wrong with that request. Please try again.