Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 219 lines (141 sloc) 6.732 kB
7b9e0f5 @vijaydev minor change in AR readme [ci skip]
vijaydev authored
1 = Active Record -- Object-relational mapping in 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
df36a3b @zzak :scissors:
zzak authored
22
a923375 @vijaydev fix formatting errors [ci skip]
vijaydev authored
23 {Learn more}[link:classes/ActiveRecord/Base.html]
df36a3b @zzak :scissors:
zzak authored
24
e5ac6c8 @gaurish Fix Formatting in AR Readme
gaurish authored
25 The Product class is automatically mapped to the table named "products",
26 which might look like this:
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
27
db045db @dhh Initial
dhh authored
28 CREATE TABLE products (
29 id int(11) NOT NULL auto_increment,
30 name varchar(255),
31 PRIMARY KEY (id)
32 );
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
33
6252d0a @manish-shrivastava updated Inline format at activerecord rdoc
manish-shrivastava authored
34 This would also define the following accessors: <tt>Product#name</tt> and
35 <tt>Product#name=(new_name)</tt>.
df36a3b @zzak :scissors:
zzak authored
36
db045db @dhh Initial
dhh authored
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
f4d818d @rafaelfranca Revert "Removing composed_of from ActiveRecord."
rafaelfranca authored
49 * Aggregations of value objects.
50
51 class Account < ActiveRecord::Base
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
52 composed_of :balance, class_name: 'Money',
53 mapping: %w(balance amount)
f4d818d @rafaelfranca Revert "Removing composed_of from ActiveRecord."
rafaelfranca authored
54 composed_of :address,
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
55 mapping: [%w(address_street street), %w(address_city city)]
f4d818d @rafaelfranca Revert "Removing composed_of from ActiveRecord."
rafaelfranca authored
56 end
57
58 {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
59
60
db045db @dhh Initial
dhh authored
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
da4252f @alvaropereyra Updates validations examples to be more attuned on the new Rails 3.0 …
alvaropereyra authored
64 validates :subdomain, :name, :email_address, :password, presence: true
65 validates :subdomain, uniqueness: true
66 validates :terms_of_service, acceptance: true, on: :create
67 validates :password, :email_address, confirmation: true, on: :create
6860db6 @dhh Renamed Mixins to Acts to resemble the change from include ActiveReco…
dhh authored
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 * Inheritance hierarchies.
db045db @dhh Initial
dhh authored
84
85 class Company < ActiveRecord::Base; end
86 class Firm < Company; end
87 class Client < Company; end
88 class PriorityClient < Client; end
89
c4e5196 @dhh Updated documentation even more
dhh authored
90 {Learn more}[link:classes/ActiveRecord/Base.html]
db045db @dhh Initial
dhh authored
91
92
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
93 * Transactions.
db045db @dhh Initial
dhh authored
94
aa4af60 @lifo Improve documentation.
lifo authored
95 # Database transaction
db045db @dhh Initial
dhh authored
96 Account.transaction do
97 david.withdrawal(100)
98 mary.deposit(100)
99 end
100
c4e5196 @dhh Updated documentation even more
dhh authored
101 {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
db045db @dhh Initial
dhh authored
102
103
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
104 * Reflections on columns, associations, and aggregations.
db045db @dhh Initial
dhh authored
105
106 reflection = Firm.reflect_on_association(:clients)
107 reflection.klass # => Client (class)
108 Firm.columns # Returns an array of column descriptors for the firms table
109
c4e5196 @dhh Updated documentation even more
dhh authored
110 {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
db045db @dhh Initial
dhh authored
111
112
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
113 * Database abstraction through simple adapters.
db045db @dhh Initial
dhh authored
114
d5ee17e @mislav improve Active Record README
mislav authored
115 # connect to SQLite3
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
116 ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: 'dbfile.sqlite3')
db045db @dhh Initial
dhh authored
117
d5ee17e @mislav improve Active Record README
mislav authored
118 # connect to MySQL with authentication
119 ActiveRecord::Base.establish_connection(
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
120 adapter: 'mysql2',
121 host: 'localhost',
122 username: 'me',
123 password: 'secret',
124 database: 'activerecord'
d5ee17e @mislav improve Active Record README
mislav authored
125 )
db045db @dhh Initial
dhh authored
126
d5ee17e @mislav improve Active Record README
mislav authored
127 {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for
128 MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html],
129 PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], and
130 SQLite3[link:classes/ActiveRecord/ConnectionAdapters/SQLite3Adapter.html].
db045db @dhh Initial
dhh authored
131
132
fc63e80 @zzak Use github url for homepage of log4r [ci skip]
zzak authored
133 * Logging support for Log4r[https://github.com/colbygk/log4r] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc].
db045db @dhh Initial
dhh authored
134
0023643 @Karunakar Moved all the logger methods to active support logger
Karunakar authored
135 ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT)
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
136 ActiveRecord::Base.logger = Log4r::Logger.new('Application Log')
db045db @dhh Initial
dhh authored
137
138
6fbd548 @waynn add a missing "the" and normalize the use of periods.
waynn authored
139 * Database agnostic schema management with Migrations.
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
140
141 class AddSystemSettings < ActiveRecord::Migration
55b203d @amatsuda self.up, self.down => up, down
amatsuda authored
142 def up
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
143 create_table :system_settings do |t|
d5ee17e @mislav improve Active Record README
mislav authored
144 t.string :name
145 t.string :label
146 t.text :value
147 t.string :type
148 t.integer :position
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
149 end
150
82355df update code examples to 1.9 hash syntax in the AR/README [ci skip]
Francesco Rodriguez authored
151 SystemSetting.create name: 'notice', label: 'Use notice?', value: 1
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
152 end
153
55b203d @amatsuda self.up, self.down => up, down
amatsuda authored
154 def down
96980bd @dhh Added change_table for migrations (Jeff Dean) [#71 state:resolved]
dhh authored
155 drop_table :system_settings
156 end
157 end
158
159 {Learn more}[link:classes/ActiveRecord/Migration.html]
160
db045db @dhh Initial
dhh authored
161
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
162 == Philosophy
db045db @dhh Initial
dhh authored
163
d5ee17e @mislav improve Active Record README
mislav authored
164 Active Record is an implementation of the object-relational mapping (ORM)
165 pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html] by the same
166 name described by Martin Fowler:
db045db @dhh Initial
dhh authored
167
d5ee17e @mislav improve Active Record README
mislav authored
168 "An object that wraps a row in a database table or view,
169 encapsulates the database access, and adds domain logic on that data."
db045db @dhh Initial
dhh authored
170
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
171 Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is
db045db @dhh Initial
dhh authored
172 object-relational mapping. The prime directive for this mapping has been to minimize
6ab9f2b @dhh Fix READMEs (closes #2680) [coffee2code]
dhh authored
173 the amount of code needed to build a real-world domain model. This is made possible
db045db @dhh Initial
dhh authored
174 by relying on a number of conventions that make it easy for Active Record to infer
175 complex relations and structures from a minimal amount of explicit direction.
176
177 Convention over Configuration:
54644f2 @waynn XML-files isn't a word
waynn authored
178 * No XML files!
db045db @dhh Initial
dhh authored
179 * Lots of reflection and run-time extension
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
180 * Magic is not inherently a bad word
db045db @dhh Initial
dhh authored
181
182 Admit the Database:
183 * Lets you drop down to SQL for odd cases and performance
184 * Doesn't attempt to duplicate or replace data definitions
185
186
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
187 == Download and installation
db045db @dhh Initial
dhh authored
188
b905f8c @sukeerthiadiga Rubygems => RubyGems
sukeerthiadiga authored
189 The latest version of Active Record can be installed with RubyGems:
db045db @dhh Initial
dhh authored
190
0080a88 @claudiob [ci skip] Don’t encourage `sudo gem install`
claudiob authored
191 % gem install activerecord
db045db @dhh Initial
dhh authored
192
c9f7546 @waynn make the headers consistent
waynn authored
193 Source code can be downloaded as part of the Rails project on GitHub:
db045db @dhh Initial
dhh authored
194
9e39fd9 Removed trailing slash of 'Download and installation' Github URL as p…
ejy authored
195 * https://github.com/rails/rails/tree/master/activerecord
db045db @dhh Initial
dhh authored
196
197
198 == License
199
2315e96 @imkmf Finished implementation of MIT license linking.
imkmf authored
200 Active Record is released under the MIT license:
201
202 * http://www.opensource.org/licenses/MIT
db045db @dhh Initial
dhh authored
203
204
205 == Support
206
c9f7546 @waynn make the headers consistent
waynn authored
207 API documentation is at:
db045db @dhh Initial
dhh authored
208
bfb9f75 @Karunakar changed http://api.rubyonrails.com to http://api.rubyonrails.org in …
Karunakar authored
209 * http://api.rubyonrails.org
db045db @dhh Initial
dhh authored
210
4c66ab2 @zzak Feature requests should be made on the mailing list, not submitted to
zzak authored
211 Bug reports can be filed for the Ruby on Rails project here:
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
212
9870afb @arunagw Some readme fixes as required.
arunagw authored
213 * https://github.com/rails/rails/issues
4c66ab2 @zzak Feature requests should be made on the mailing list, not submitted to
zzak authored
214
215 Feature requests should be discussed on the rails-core mailing list here:
216
217 * https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core
218
Something went wrong with that request. Please try again.