Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 223 lines (145 sloc) 6.923 kB
d5ee17e @mislav improve Active Record README
mislav authored
1 = Active Record -- Object-relational mapping put on rails
db045db @dhh Initial
dhh authored
2
d5ee17e @mislav improve Active Record README
mislav authored
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
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
6 class and an existing table in the database. In the context of an application,
d5ee17e @mislav improve Active Record README
mislav authored
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
9
d5ee17e @mislav improve Active Record README
mislav authored
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
15
d5ee17e @mislav improve Active Record README
mislav authored
16 A short rundown of some of the major features:
db045db @dhh Initial
dhh authored
17
18 * Automated mapping between classes and tables, attributes and columns.
19
d5ee17e @mislav improve Active Record README
mislav authored
20 class Product < ActiveRecord::Base
21 end
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
22
d5ee17e @mislav improve Active Record README
mislav authored
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
25
db045db @dhh Initial
dhh authored
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
31
d5ee17e @mislav improve Active Record README
mislav authored
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
34
c4e5196 @dhh Updated documentation even more
dhh authored
35 {Learn more}[link:classes/ActiveRecord/Base.html]
db045db @dhh Initial
dhh authored
36
37
d5ee17e @mislav improve Active Record README
mislav authored
38 * Associations between objects defined by simple class methods.
db045db @dhh Initial
dhh authored
39
40 class Firm < ActiveRecord::Base
41 has_many :clients
42 has_one :account
d5ee17e @mislav improve Active Record README
mislav authored
43 belongs_to :conglomerate
db045db @dhh Initial
dhh authored
44 end
45
c4e5196 @dhh Updated documentation even more
dhh authored
46 {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
db045db @dhh Initial
dhh authored
47
48
d5ee17e @mislav improve Active Record README
mislav authored
49 * Aggregations of value objects.
db045db @dhh Initial
dhh authored
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
54 composed_of :address,
db045db @dhh Initial
dhh authored
55 :mapping => [%w(address_street street), %w(address_city city)]
56 end
57
c4e5196 @dhh Updated documentation even more
dhh authored
58 {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
db045db @dhh Initial
dhh authored
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
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
69
c4e5196 @dhh Updated documentation even more
dhh authored
70 {Learn more}[link:classes/ActiveRecord/Validations.html]
db045db @dhh Initial
dhh authored
71
72
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
73 * Callbacks available for the entire life cycle (instantiation, saving, destroying, validating, etc.).
d5ee17e @mislav improve Active Record README
mislav authored
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
78 end
79
c4e5196 @dhh Updated documentation even more
dhh authored
80 {Learn more}[link:classes/ActiveRecord/Callbacks.html]
db045db @dhh Initial
dhh authored
81
82
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
83 * Observers that react to changes in a model.
db045db @dhh Initial
dhh authored
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
87 CommentMailer.new_comment_email("david@loudthinking.com", comment).deliver
db045db @dhh Initial
dhh authored
88 end
89 end
90
c4e5196 @dhh Updated documentation even more
dhh authored
91 {Learn more}[link:classes/ActiveRecord/Observer.html]
db045db @dhh Initial
dhh authored
92
93
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
94 * Inheritance hierarchies.
db045db @dhh Initial
dhh authored
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
101 {Learn more}[link:classes/ActiveRecord/Base.html]
db045db @dhh Initial
dhh authored
102
103
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
104 * Transactions.
db045db @dhh Initial
dhh authored
105
aa4af60 @lifo Improve documentation.
lifo authored
106 # Database transaction
db045db @dhh Initial
dhh authored
107 Account.transaction do
108 david.withdrawal(100)
109 mary.deposit(100)
110 end
111
c4e5196 @dhh Updated documentation even more
dhh authored
112 {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
db045db @dhh Initial
dhh authored
113
114
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
115 * Reflections on columns, associations, and aggregations.
db045db @dhh Initial
dhh authored
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
121 {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
db045db @dhh Initial
dhh authored
122
123
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
124 * Database abstraction through simple adapters.
db045db @dhh Initial
dhh authored
125
d5ee17e @mislav improve Active Record README
mislav authored
126 # connect to SQLite3
127 ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "dbfile.sqlite3")
db045db @dhh Initial
dhh authored
128
d5ee17e @mislav improve Active Record README
mislav authored
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
131 :adapter => "mysql2",
d5ee17e @mislav improve Active Record README
mislav authored
132 :host => "localhost",
133 :username => "me",
134 :password => "secret",
135 :database => "activerecord"
136 )
db045db @dhh Initial
dhh authored
137
d5ee17e @mislav improve Active Record README
mislav authored
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
142
143
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
144 * Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc].
db045db @dhh Initial
dhh authored
145
146 ActiveRecord::Base.logger = Logger.new(STDOUT)
147 ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
148
149
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
150 * Database agnostic schema management with Migrations.
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
151
152 class AddSystemSettings < ActiveRecord::Migration
55b203d @amatsuda self.up, self.down => up, down
amatsuda authored
153 def up
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
154 create_table :system_settings do |t|
d5ee17e @mislav improve Active Record README
mislav authored
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
160 end
161
162 SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
163 end
164
55b203d @amatsuda self.up, self.down => up, down
amatsuda authored
165 def down
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
166 drop_table :system_settings
167 end
168 end
169
170 {Learn more}[link:classes/ActiveRecord/Migration.html]
171
db045db @dhh Initial
dhh authored
172
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
173 == Philosophy
db045db @dhh Initial
dhh authored
174
d5ee17e @mislav improve Active Record README
mislav authored
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
178
d5ee17e @mislav improve Active Record README
mislav authored
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
181
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
182 Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is
db045db @dhh Initial
dhh authored
183 object-relational mapping. The prime directive for this mapping has been to minimize
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
184 the amount of code needed to build a real-world domain model. This is made possible
db045db @dhh Initial
dhh authored
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
191 * Magic is not inherently a bad word
db045db @dhh Initial
dhh authored
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
198 == Download and installation
db045db @dhh Initial
dhh authored
199
b905f8c @sukeerthiadiga Rubygems => RubyGems
sukeerthiadiga authored
200 The latest version of Active Record can be installed with RubyGems:
db045db @dhh Initial
dhh authored
201
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
202 % [sudo] gem install activerecord
db045db @dhh Initial
dhh authored
203
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
204 Source code can be downloaded as part of the Rails project on GitHub
db045db @dhh Initial
dhh authored
205
9e39fd9 Removed trailing slash of 'Download and installation' Github URL as p…
ejy authored
206 * https://github.com/rails/rails/tree/master/activerecord
db045db @dhh Initial
dhh authored
207
208
209 == License
210
b3bfe13 @dhh Updated the license (still referered to the old ruby one)
dhh authored
211 Active Record is released under the MIT license.
db045db @dhh Initial
dhh authored
212
213
214 == Support
215
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
216 API documentation is at
db045db @dhh Initial
dhh authored
217
bfb9f75 @Karunakar changed http://api.rubyonrails.com to http://api.rubyonrails.org in …
Karunakar authored
218 * http://api.rubyonrails.org
db045db @dhh Initial
dhh authored
219
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
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
222 * https://github.com/rails/rails/issues
Something went wrong with that request. Please try again.