Before Active Record can work any of its Object-Relational Mapping (ORM) magic, it needs to know what kind of database it will be working with, and how it's going to connect to that database. In a Rails application, this is defined in a configuration file config/database.yml. Rails loads the options defined in this file, stores them in a hash accessible as ActiveRecord::Base.configurations, and uses them to establish its database connections. By default, a freshly generated app starts off with a simple database setup that lets you get up and running without any manual configuration. Here's what an untouched (and fully functional) database.yml looks like:

# SQLite version 3.x
#   gem install sqlite3
#
#   Ensure the SQLite 3 gem is defined in your Gemfile
#   gem 'sqlite3'
development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

# Warning: The database defined as "test" will be erased and
# re-generated from your development database when you run "rake".
# Do not set this db to the same as development or production.
test:
  adapter: sqlite3
  database: db/test.sqlite3
  pool: 5
  timeout: 5000

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

The adapter properties here are set so that each application environment gets its own SQLite3 database to work with. You will need to have the sqlite3 gem installed before things will work properly. SQLite3 stores databases as single files with locations indicated by the database property of each environment’s configuration, and each database is created automatically if it doesn’t already exist. The pool property determines the maximum number of database connections in Active Record's connection pool. The timeout property is specific to the SQLite3 adapter, setting a timeout for accessing locked tables (in milliseconds).

If you want a new Rails application to be generated with defaults for some other database adapter, you can use the --database option:

$ rails new myapp --database=mysql

This will produce a different database.yml because the MySQL adapter works differently and requires a different set of information to manage its connections.

Unless you are using one of the SQLite adapters, you will probably have to create your application's databases manually. Thankfully, Rails provides a rake task which nicely wraps this chore into a single command:

$ rake db:create

Like many rake tasks in Rails, db:create looks at the RAILS_ENV environment variable to determine which application environment to operate on, and defaults to working with the development environment. This means that the above command would create the development environment's database, with a name (or filename, in the case of SQLite databases) equal to the value of ActiveRecord::Base.configurations['development']['database']. If you want to create databases for all of the environments listed in database.yml in one fell swoop, there's a rake task for that too:

$ rake db:create:all

Wouldn’t it be nice if your models were automagically mapped to their corresponding database tables?

Rails does that by way of its convention-over-configuration approach to naming files, classes representing models, and their corresponding database tables. Each model in a Rails application is a subclass of ActiveRecord::Base, and follows the Ruby convention of having capitalized CamelCase class names. The model’s filename should be like the class name, but all in underscored lowercase. That is to say: a School model would be defined in school.rb, and a CourseEnrollment model would be defined in course_enrollment.rb.

The other name associated with a model is its database table name, which by default is the pluralized form of the file’s base name: the School model’s records live in a schools table; CourseEnrollment records live in a course_enrollments table.

After your application has a database to work with, you can start populating it with the tables, columns, and indexes that define your schema. The primary means of developing the schema is by creating a number of small Ruby files called migrations. A typical Rails application will end up with a growing number of migrations as development progresses and the schema evolves. Each migration forms a link in a sequential chain of alterations to the database schema. The migration files are stored in db/migrate and each one usually consists of just a single class with two method definitions: up and down. Here's an example of what generating a migration looks like in the terminal:

$ rails generate migration CreateUsersAndClouds
      invoke  active_record
      create    db/migrate/20110918024931_create_users_and_clouds.rb

We gave the generator the name of the migration, and it created a single file for us. The long string of numbers at the beginning of the filename is a timestamp from whenever the migration is generated. This is how Rails maintains a consistent ordering of migrations and keeps track of which migrations have already been run. Here is the migration skeleton which has been generated for us:

class CreateUsersAndClouds < ActiveRecord::Migration
  def up
  end

  def down
  end
end

The file contains a subclass of ActiveRecord::Migration using the name we passed to the generator. The up method is going to contain the changes we want to make to our schema; the down method will define how those changes can be undone. So for example, a create_table call in the up method should be probably be paired with a corresponding drop_table call in the down method.

create_table :people do |t|
  t.string :name
end

create_table :weblogs_users, :id => false do |t|
  t.integer :weblog_id, :user_id
end

change_table :people do |t|
  t.string :email
  t.index  :email, :unique => true
end

drop_table :people

create_table :users,  do |t|
  t.string  :name
  t.string  :email
  t.string  :password
  t.date    :birthday
end

create_table :users do |t|
  t.column :name,        :string
  t.column :email,       :string
  t.column :password,    :string
  t.column :birthday,    :date
end

add_column    :users, :active_subscription_id, :integer
remove_column :users, :password

change_column :users, :email, :null => false

change_table :users do |t|
  t.change  :email, :null => false
  t.boolean :admin
  t.remove  :birthday
end

create_table :things, :id => false do |t|
  t.primary_key :number
end

change_table :users do |t|
  t.timestamps
end

create_table :plants do |t|
  t.belongs_to :species
end

change_table :plants do |t|
  t.belongs_to :owner, :polymorphic => true
end

One of the key differences between relational databases and object-oriented systems is the way that hierarchical data is represented. In an object-oriented program, a Person object might have many Puppy objects associated with it as pets, with the Person keeping track of its puppies by storing references to them in a collection object of some kind.

In a relational database, however, the child entities keep track of the parents: each row in the puppies table would reference an associated row in the people table by storing its owner’s primary key in a special column in the puppies table. As long as an index is maintained for the foreign key column, queries to find either a particular student’s school or a particular person’s puppies can be completed very quickly without the database having to look at each student row one at a time.

Active Record makes all this very easy to deal with, letting you type out things like person.puppies and get back what you expect. Here's how you make it happen:

class Person < ActiveRecord::Base
  has_many :puppies
end

Besides the people table itself, all this requires is a puppies table with a column called person_id. The has_many method is a class method on ActiveRecord::Base which defines a public instance method on Person called puppies. This method returns an array-like object which gives access to all the puppies which have the person's id in their person_id column.

By declaring the has_many macro in the Person class, we are defining an association on that class, and Active Record does a fair bit of work behind the scenes to keep track of the association and provide convenient ways for you to manage a record’s relationships with other records. In order to get the same kind of convenience on the other side of the puppy-owner relationship, we would make a similar declaration in the Puppy class:

class Puppy < ActiveRecord::Base
  belongs_to :person
end

class Puppy < ActiveRecord::Base
  belongs_to :owner, :class_name => "Person"
end

class Person < ActiveRecord::Base
  has_many   :puppies
  has_one    :mailing_address
end

class User < ActiveRecord::Base
  has_many    :articles,  :foreign_key => :author_id
  has_many    :events,    :foreign_key => :organizer_id
end

class Article < ActiveRecord::Base
  belongs_to  :author,    :class_name => 'User'
end

class Event < ActiveRecord::Base
  belongs_to  :organizer, :class_name => 'User'
end

class Article < ActiveRecord::Base
  has_many    :comments,  :as => :subject
end

class Event < ActiveRecord::Base
  has_many    :comments,  :as => :subject
end

class Comment < ActiveRecord::Base
  belongs_to  :subject,   :polymorphic => true
end

A database row's column values are mapped to attributes on an Active Record object. Active Record uses the schema of the model’s table to figure out what attributes a record will have.

The most common way to access attributes is by using the standard getters and setters defined dynamically by Active Record:

puppy.name     # => "frank"
puppy.demeanor # => "grizzled"
puppy.demeanor = "repentant"

The attribute values returned from these accesssors have already run through Active Record’s type conversion process (see the section called “Type Mapping” for a list of which ruby types get returned from which columns).

student.changed?                 # => false
student.middle_name = 'Ambrose'
student.changed?                 # => true
student.save
student.changed?                 # => false

student.gpa = 3.22
student.gpa_changed?             # => true
student.gpa_was                  # => 3.14
student.gpa_change               # => [3.22, 3.14]
                

student.middle_name = 'David'
student.changed
  # => ["gpa", "middle_name"]
student.changes
  # => {"gpa" => [3.22, 3.14], "middle_name" => ["Ambrose", "David"]}

student.save
student.middle_name_will_change!
student.middle_name_changed?     # => false
student.middle_name << 'son'
student.middle_name_change       # => ["David", "Davidson"]

Active Record uses Active Model’s validation system to check a record’s attributes before it is saved to the database.

Validations are run automatically before an Active Record object is saved to the database, and if any errors are found then the save will fail. You can also check the validity of an object whenever you want by calling valid? on that object. Whenever an object’s validations are run, any resulting errors are accessible through its errors accessor.

class User < ActiveRecord::Base
  validates :email, :presence => true, :format => {:with => /@/}
end

class User < ActiveRecord::Base
  validates_presence_of :email
  validates_format_of :email, :with => /@/
end

class User < ActiveRecord::Base
  validates :home_email, :work_email, :presence => true
  validates_format_of :home_email, :work_email, :with => /@/
end

class User < ActiveRecord::Base
  validates :acceptance => :terms_of_service
  # or:
  # validates_acceptance_of :terms_of_service
end

<% form_for @user do |user| %>
  ...
  <%= user.check_box :terms_of_service %>
<% end %>

class User < ActiveRecord::Base
  has_one :mailing_address

  validates_associated :mailing_address
  # validates :mailing_address, :associated => true
end

class User < ActiveRecord::Base
  validates_confirmation_of :password
  # validates :password, :confirmation => true
end

class User < ActiveRecord::Base
  validates_exclusion_of :name,
    :in => ['Kirk', 'Spock', 'Bones']
  # validates :name, :exclusion => {:in => ['Kirk', 'Spock', 'Bones']}
end

class User < ActiveRecord::Base
  validates_format_of :email, :with => /@/
  # validates :email, :format => {:with => /@/}
end

class User < ActiveRecord::Base
  validates_inclusion_of :date_of_birth,
    :in => (130.years.ago.to_date .. Date.today),
    :message => "must be at least plausibly human"
  # validates :date_of_birth, :inclusion => {
  #   :in => (130.years.ago.to_date .. Date.today),
  #   :message => "must be at least plausibly human"
  # }
end

class User < ActiveRecord::Base
  validates_length_of :password, :in => 6..255
  # validates :password, :length => {:in => 6..255}
end

class Product < ActiveRecord::Base
  validates_numericality_of :price,
    :greater_than_or_equal_to => 0.00,
    :message => "must be a non-negative number"
  # validates :price, :numericality => {
  #   :greater_than_or_equal_to => 0.00,
  #   :message => "must be a non-negative number"
  # }
end

class User < ActiveRecord::Base
  validates_presence_of :name, :email, :password
  # validates :name, :email, :password, :presence => true
end

class User < ActiveRecord::Base
  validates_uniqueness_of :email
  # validates :email, :uniqueness => true
end

class Log < ActiveRecord::Base
  validates_uniqueness_of :name, :scope => :user_id
  # validates :name, :uniqueness => {:scope => :user_id}
end

class User < ActiveRecord::Base
  validates_each :first_name, :last_name do |record, attribute, value|
    if ['Kirk', 'Spock', 'Bones'].include?(value)
      record.errors.add(attribute, "must not have served on the Enterprise")
    end
  end
end

student.gpa = 9000
student.save(:validate => false)

Callbacks are hooks which let you run some code when particular events like creation and destruction happen to a model object. You can define callbacks on a model in two different ways. One way is to define an instance method on the model class, naming the method after the callback in question:

class Student < ActiveRecord::Base
  def before_destroy
    AlumniMailer.deliver_request_for_donations(self)   
  end
end

Another way is to use the callback macros, which are Active Record class methods named after the various callbacks. Callback macros take a few different kinds of arguments: symbols, Procs, and callback objects. You can pass as many of these arguments as you want in any combination. The most common type of argument is a symbol:

class Student < ActiveRecord::Base
  before_create :generate_card_number

  protected
  def generate_card_number
    self.card_number = "1%02d%06d" % [rand(100), self.id]
  end
end

The symbol must refer to an instance method on the model object, which is run when the callback is triggered. Similarly, Proc objects which have been passed to the callback macro will be executed directly.

There are seven different events for which ActiveRecord has built-in callbacks:

Rails projects tend to have rather flat class hierarchies. Most of the time, Ruby makes it easier to implement and maintain shared behaviour by using mixin modules instead of a rigid inheritance tree. If you have two Active Record models which both have many of the same attributes, you can define a common interface for them in a module that you include in both classes.

Sometimes, however, you have multiple entities in your data model which are just so similar that it seems silly to keep them apart. Active Record lets you do this through its implementation of the single table inheritance pattern (STI): if you give one of your tables a type column, Active Record will use it to store the class name of the model associated with that record. Any time that record is retrieved from the database, Active Record will instantiate it as the appropriate class. You can then develop a little family of model classes and they'll be managed in a pretty intuitive way.

Here’s an example that could be part of a very minimal microblogging app:

class Log < ActiveRecord::Base
  has_many :entries, :order => 'created_at DESC'
  has_many :idea_entries
  has_many :image_entries
  has_many :video_entries
end

class Entry < ActiveRecord::Base
  belongs_to :log
  attr_accessible :title
end

class IdeaEntry < Entry
  attr_accessible :content, :subject_url
  validates_presence_of :content
end

class ImageEntry < Entry
  attr_accessible :subject_url
  validates_presence_of :subject_url
end

class VideoEntry < Entry
  attr_accessible :subject_url
  validates_presence_of :subject_url
end

Now we can call Log.entries and get all of the associated IdeaPost, ImagePost, and VideoPost records together, sorted in reverse chronological order, instantiated as the correct classes, all with only one database query. If we'd kept the different types of posts in separate tables, we would have to use three separate associations with three database queries, and then combine them and sort them ourselves.

ActiveRecord lets you go beyond its default type mapping if you need to give your models rich attributes with custom behaviour of their own. These are called aggregations, and you define them with the macro composed_of. Here's what it looks like:

class Person < ActiveRecord::Base
  composed_of :hair_color, :class_name => 'Color', :mapping => [:hair_color, :to_s]
end

Similar to the association macros, the ultimate result of composed_of is the definition of instance accessor methods for the new aggregated attribute. The method’s first argument is the name you choose to give the aggregated attribute you are defining. The second argument is an options hash, which almost always contains a :mapping option designating the pairs of corresponding attributes between the Active Record model and the aggregated object. It also needs a :class_name option if the name of the aggregated attribute's class is not simply the CamelCase of the first argument.

The :mapping option in the above code would rely on the Person model already having a hair_color attribute. Calling person.hair_color would try to instantiate a new instance of the class Color, which you would have to define elsewhere. The constructor method would be called with the value of the hair_color attribute on that particular instance of Person.

person.hair_color
# roughly equivalent to:
# Color.new(person.read_attribute(:hair_color))

person.hair_color = Color.new("red")
# roughly equivalent to:
# person.write_attribute(:hair_color, Color.new("red").to_s)

You can create an Active Record object the same way you would with most other Ruby objects: by calling the new method on the appropriate class:

cloud = Cloud.new
cloud.inspect
# => "#<Cloud id: nil, contributor_id: nil, url: nil, looks_like: nil, created_at: nil, updated_at: nil>"

Nothing is saved to the database yet; all we've done is create an instance of Cloud in memory. Because we didn’t specify any of the values for its attributes, the new object is initialized with nil for each of them. Even the primary key id attribute is blank at this point, since it is determined only when the object is saved to the database as a record. You can also pass a hash of attribute-value pairs to Cloud’s initializer if you want to start the object off with some novel data. Either way, once the object is created you can access its attributes via accessor methods generated automatically by Active Record:

cloud = Cloud.new(:filepath => 'neato_dumbo_cloud.jpg')
cloud.looks_like = 'elephant'

Once the cloud’s attributes are how we want them, we can save the cloud to the database:

cloud.save
# => true

Active Record’s save method tries to save the model as a record in the database. If it is saved successfully, it returns true. If it fails for any reason, it returns false. The most common way for a save to fail is because the model's validations have not been satisfied correctly. See the section called “Validations” for details on how to define validations for your models. There's also a whiny version of the method which will raise an exception if the save encounters any errors:

cloud.save!
# => true

There are a number of ways available to look up existing database records and generate Active Record objects from them. There is one class method available on each of your models which serves as the primary interface for looking up records. This method is called find, and operates in one of a few different modes depending on the first argument passed to it.

If the first argument is an integer, you will get new Active Record instances corresponding to the record with the given id column value(s):

Cloud.find(1)
# => #<Cloud id: 1, filepath: 'neato_dumbo_cloud.jpg', 
  looks_like: "elephant", created_at: "2009-02-16 22:23:10", 
  updated_at: "2009-02-16 22:23:10">

Cloud.find(1,2)
# => [#<Cloud id: 1, filepath: 'neato_dumbo_cloud.jpg', 
  looks_like: "elephant", created_at: "2009-02-16 22:23:10", 
  updated_at: "2009-02-16 22:23:10">, 
  #<Cloud id: 2, filepath: 'weird_cloud.jpg', 
  looks_like: "heart", created_at: "2009-02-16 22:23:10", 
  updated_at: "2009-02-16 22:33:06">]

If any of the given id values do not correspond to those of existing records in the clouds table, then the find method will raise an ActiveRecord::RecordNotFound error. If you don't know or don’t care what a cloud’s id is, you can get the first or last cloud in the database with first and last:

Cloud.first
# => #<Cloud id: 1, filepath: 'neato_dumbo_cloud.jpg', looks_like: "elephant", 
  created_at: "2009-02-16 22:23:10", updated_at: "2009-02-16 22:23:10">

Cloud.last
# => #<Cloud id: 2, filepath: 'weird_cloud.jpg', looks_like: "heart", 
  created_at: "2009-02-16 22:23:10", updated_at: "2009-02-16 22:33:06">

These method calls would each return nil if the clouds table were empty; they won’t raise an exception like they would if they were given specific ids. You can get an array of all clouds in the database with all:

Cloud.all
# => [#<Cloud id: 1, filepath: 'neato_dumbo_cloud.jpg', looks_like: "elephant", 
  created_at: "2009-02-16 22:23:10", updated_at: "2009-02-16 22:23:10">, 
  #<Cloud id: 2, filepath: 'weird_cloud.jpg', looks_like: "heart", 
  created_at: "2009-02-16 22:23:10", updated_at: "2009-02-16 22:33:06">]

If the clouds table were empty, this method call would just return an empty array.

No matter which mode you are using with find, you can alter the way records are retrieved by providing a hash of options as the last argument. Almost all of these options directly correspond with fragments of SQL which are incorporated into the the SELECT query generated by ActiveRecord.

Active Record relations let you construct SQL queries in a flexible way. The simplest relation of a model represents all of its table’s rows and columns. You can access this relation with the model’s class method scoped:

Puppy.scoped
# => <#ActiveRecord::Relation ... >

A relation’s inspect method ends up instantiating a collection of Active Record objects based on the results of its query. If you want to verify the logic of a relation instead of fetching its contents, you can easily look at the SQL that is being constructed:

Puppy.scoped.to_sql
# => "SELECT ..."

The SQL returned here is a SELECT statement, but relations may also be used to execute creations, updates, and deletions. Relations are constructed in a modular fashion by chaining together query-builder methods. Each method returns a new relation object based on the one returned by the previous method. The order of the methods does not matter: you could put a select after a group, even though

Most of the query builder methods directly correspond to clauses available in an SQL SELECT statement, like WHERE and GROUP BY. You don't need to call scoped first to get the base relation, you can just call the query builder methods on the ActiveRecord::Base object itself.

Puppy.where(:demeanor => "dismissive").group(:name).order("count(*) DESC").to_sql

You can also build relations off of has_many associations:

kathy.puppies.where(:demeanor => "vigilant").to_sql
# => "SELECT ..."

If you've

Figure 4.1. A Relation and its SQL

Cloud.where(:looks_like => 'elephant').to_sql
# => SELECT * FROM "clouds" WHERE ("clouds"."looks_like" = 'elephant')

Cloud.where(:looks_like => ['elephant', 'mouse']).all
# => SELECT * FROM "clouds" WHERE ("clouds"."looks_like" IN ('elephant','mouse'))

Cloud.where(:id => 1..20).all
# => SELECT * FROM "clouds" WHERE ("clouds"."id" BETWEEN 1 AND 20)

Cloud.where(:created_at => (Time.now - 2.weeks)..(Time.now)).all
# => SELECT * FROM "clouds"
#    WHERE ("clouds"."created_at" BETWEEN '2009-02-07 16:30:35' AND '2009-02-21 16:30:35')

Cloud.where(["looks_like LIKE ? AND updated_at > ?", "%#{params[:q]}%", 2.weeks.ago]).all
# => SELECT * FROM "clouds" WHERE (looks_like LIKE '%squirrel%' AND 
  updated_at > '2009-03-01 20:26:16') 

Cloud.where(["looks_like LIKE :query AND
              updated_at > :updated_since AND
              created_at < :created_until",
              { :query => "%#{params[:q]}%",
                :updated_since => 2.weeks.ago,
                :created_until => 3.hours.ago }
             ]).all
# => SELECT * FROM "clouds" WHERE (looks_like LIKE '%squirrel%' AND
#     updated_at > '2009-03-01 21:40:47' AND
#     created_at < '2009-03-15 18:40:47')

Cloud.where('updated_at > "2008"').all
# => SELECT * FROM "clouds" WHERE (updated_at > "2008")

relation.select(SQL)

Puppy.scoped.to_sql
# =>
Puppy.select("id, name").to_sql
# =>

puppies = Puppy.select("id, name, people.name as owner_name").joins(:owner)
puppies.to_sql
# =>
puppies.first["owner_name"]
# =>

relation.group(*columns).having(*conditions)

Puppy.group(:name).having("count(name) > 2").to_sql
# => "SELECT \"puppies\".* FROM \"puppies\"  GROUP BY name HAVING count(name) > 2"

relation.order(*orderings)

relation.limit(limit).offset(offset)

relation.includes(*associations)

Tumblelog.includes(:posts => [:author, {:comments => :author}])

relation.joins(*associations)
relation.joins(SQL)

relation.lock
relation.lock(locking_clause)

relation.readonly

relation.from(table)

relation.only(*methods)
relation.except(*methods)

rel = Puppy.where(:name => "Frank").order(:created_at).limit(3)
rel.to_sql
# =>
rel.only(:where).to_sql
# =>
rel.except(:where, :order).to_sql
# =>

If you just want to get the results of some aggregate calculations on the records in a relation, it’s going to be a lot faster to let the database do it instead of instantiating a bunch of Active Record objects and iterating over them in Ruby.

relation.calculate(function, column)

The function is the name of an aggregate function in SQL. The most common calculations have their own convenience methods:

relation.average(column)
relation.count(column)
relation.maximum(column)
relation.minimum(column)
relation.sum(column)

If relation was built with a call to group at any point in its construction, then calculate will return an ordered hash which maps the values of the grouped attributes to the results of the calculations. If no group was used, it returns a single value.

Puppy.average(:weight_in_kg)
# => #<BigDecimal ...>
Puppy.group(:name).count
# => #<OrderedHash ...>

The most common way of updating existing records is to work with individual Active Record objects which have been instantiated from some finder method or from another model object's association. Once you’ve retrieved the records that you’re looking for, you can update their values using the accessor methods that Active Record generates automatically based on your database schema.

column accessor example, ending with a #save

There are also a few type-specific writer methods for integer and boolean attributes:

example: decrement, increment, toggle, ending with #save

Note that no changes are sent to the database unless the save method or one of its variants is called on the object. The most common way of saving record objects is with save or save!, but there are a number of other instance methods which save the record as well:

As you can probably tell from the names of these methods, they all involve updating one or more attributes of the record and then saving the record to the database. For decrement!, increment!, and toggle!, the bang (!) suffix indicates that a save is taking place (no save is made with the bangless versions of those methods). For update_attributes!, however, the bang indicates that the whiny save! is used.

The standard way to delete a record is with the destroy method:

student.destroy

In addition to deleting the object’s record in the database, the object's attributes are also frozen to indicate that changes can no longer be propagated to the database with a call to the save method. The destroy method results in the before_destroy and after_destroy callbacks being run. If you just want to delete the record without running any callbacks, you can instead use the delete method:

student.delete

The same DELETE statement is sent to the database, but no callbacks are run, and none of an object's associations are dealt with in any way. This means that if your student objects each have an enrollments association which has been established with the :dependent => :destroy option, nothing will happen to those associated enrollments when delete is called on a student.

Some databases support the ability to run multiple updates to the database in a single atomic transaction—a block of code in which statements are guaranteed to either all succeed or all fail. In SQL, a transaction is opened with a BEGIN statement, and either finalized with COMMIT or explicitly aborted with ROLLBACK. In Active Record, this pattern is abstracted into the familiar ruby concepts of blocks and exceptions.

ActiveRecord::Base.transaction do
  david.withdrawal(100)
  mary.deposit(100)
end

To roll back the transaction explicitly, you can raise an ActiveRecord::Rollback error somewhere in the transaction block. The transaction block will rescue the error and send a ROLLBACK to the database. Actually, any error raised within a transaction block will trigger a rollback, but only ActiveRecord::Rollback will be rescued by Active Record. Other errors will continue to propagate up the call chain after the transaction has been rolled back, so you'll still have to handle them somewhere in your application.

If one transaction is nested inside another, the inner transaction block will be ignored by default. This means you should keep a few things in mind when writing transactions that may end up being run within other transactions:

If you want your inner transaction to handle rollbacks independently of the outer transaction, you can pass the :requires_new option to the inner transaction's method call.

ActiveRecord::Base.transaction(:requires_new => true) do
  david.withdrawal(100)
  mary.deposit(100)
end

Most databases don't support true nested transactions, but Active Record can emulate them by using database savepoints.

Sometimes the callbacks on your model end up having little to do with the model itself. Consider a few callbacks which create an Event record every time a Puppy record gets created, updated, or deleted.

class Puppy < ActiveRecord::Base
  has_many :events, :as => :subject
  
  def after_create
    events.create(:verb => 'create')
  end
  def after_update
    events.create(:verb => 'update')
  end
  def after_destroy
    events.create(:verb => 'destroy')
  end
end

Every time you open up puppy.rb, you're looking at a bunch of code which has more to do with events than it does with puppies. If you only ever access events through the has_many associations of puppies, then you might just consider Event to be a child model and keep the code where it is. But it would be nice to look at events on their own, as an activity log for the whole app. When there's a logical split like this between the concerns of your callback methods and the core concerns of the model, you should try observers. Here's how you might write an observer for these events, saved as app/models/event_creation_observer.rb:

class EventCreationObserver < ActiveRecord::Observer
  observe Puppy, Person
  
  def after_create(subject)
    Event.create(:subject => subject, :verb => 'create')
  end
  def after_update(subject)
    Event.create(:subject => subject, :verb => 'update')
  end
  def after_destroy(subject)
    Event.create(:subject => subject, :verb => 'destroy')
  end
end

Notice that we are now observing the Person class as well, by specifying it in the call to observe. By default, an observer will look at its own class name to find which model it should register itself with; if we had omitted the observe line, then this observer would have looked for an EventCreation model. But our Event model has a polymorphic belongs_to with both puppies and people, so we can easily use the same code to create events from both.