Active Record is implemented in Rails as a set of base classes from which your model objects extend. Each table in your database is generally represented by a class that extends an Active Record base class. Simply by extending the Active Record base classes, your model objects inherit a wealth of functionality. In fact, your model objects may be as simple as this:

class Book < ActiveRecord::Base
end

This empty class definition is enough to give your Book class quite a bit of functionality merely by extending the ActiveRecord::Base class. By using ActiveRecord::Base, Rails knows that this class wraps a database table named books. Active Record will dynamically add metadata to this class for all of the table columns that are in the books table. This includes data such as column names, types, and lengths. Active Record also adds attributes to your class for each of the columns in the database.

Active Record manages database connections for your application. You don't have to write any code to set up database connections or to manage those in your Rails application. Basically, all of the details related to working with a database are hidden from you, the developer, by Active Record. As a developer, you work with objects and do not have to deal with things like database connections, tables, columns, and SQL statements.

Active Record makes heavy use of the convention-over-configuration principle. If you follow a few simple naming conventions, you can take advantage of many dynamic features of Active Record with no configuration required.

Inflector.inflections do |inflect|
    inflect.irregular 'sheep', 'sheeps'
end

class Shape < ActiveRecord::Base
    set_table_name 'shape_items'
end

ActiveRecord::Base.pluralize_table_names = false

Table keys

There are two types of database keys for which naming is important in Rails: primary keys and foreign keys.

Primary keys

The primary key is what uniquely identifies each row in a database table. Your tables should have a primary key with the column name id. The id column should be an integer type and should be auto-incrementing. Rails will automatically use this column as a unique identifier. Rails migrations, which are discussed later in this chapter, automatically create a primary key column named id for each table that is created. If you want to use a different field as the primary key for a table, Rails allows that, but with some restrictions. See the sidebar "Using Alternate Primary Keys with Rails" for more information.

Using Alternate Primary Keys with Rails

By default, Rails uses a field called id as the primary key for all of your database tables. Rails migrations generate this field automatically so you do not have to specify it in your table creation migrations. While this field is suitable for most purposes, there may be times when you have to work with a legacy database for which you do not get to choose the primary key fields. As with many other things in Rails, you can override the default Rails primary key field name and specify any field for a particular model. You do this using the set_primary_key method in the model class definition that wraps the table for which you want an alternate primary key.

For example, say you had a table named images that contained a primary key field named image_id. In the Image model class, you would use this code:

class Image < ActiveRecord::Base
    set_primary_key "image_id"
end

The most notable restriction on using alternate primary keys in Rails is that you cannot use composite keys as primary keys. Composite keys are keys that use more than one database column. For example, a key that used the image_id field and the created_at field in combination would not be allowed as a primary key in a Rails application. This is a restriction that is often criticized by both Rails enthusiasts and antagonists. It is a restriction that is not likely to change in the near future, though, so if you're writing a Rails application, you will need to deal with it or have a strategy to overcome it. (There is a Rails plugin available that extends the database layer of Rails to support composite primary keys. If you are interested in this plugin, you can find out more about it at http://compositekeys.rubyforge.org. In Chapter 11 you will learn more about using plugins with Rails.)

Your application can use a composite key as long as it is not the primary key. As a result, if you need a composite key, perhaps you have the flexibility to add a new field to serve as your primary key.

If you do override the primary key column name, you also become responsible for creating unique primary key values. Rails will not automatically generate a primary key value for any table that contains a non-default primary key name.

When you work with a non-default primary key field name, you still refer to the primary key attribute as id when you set the primary key value for an object . However, any other time you refer to the primary key attribute, you use the name that you assigned that field in the set_primary_key method.

Foreign keys

Foreign keys are used in a table to identify a row in another table that is related to the row containing the foreign key. For example, in Figure 3.2, the book_id column in the pages table is a foreign key that relates a row in the pages table to a row in the books table. Foreign keys in a Rails application should be named with the singular name of the referenced table followed by id, just as book_id is named in Figure 3.2.

Figure 3.2. Primary and foreign keys

Begin by using a command-line and creating a Rails project, model, and database. The commandline feedback that you receive when you run the various commands throughout this chapter is not always specifically shown in this book; if you see feedback that is not shown in this book as you run the commands, don't be surprised. You should expect Rails to generate feedback from its commands, similar to what you saw in Chapter 2.

You should now have the basic elements you need to follow along with the examples in this chapter: a Rails project named chapter3, a model within that chapter named ComicBook, and a MySQL database named comic_books_development.

You may have noticed that you gave your database a different name from the name you gave the Rails project. When the database is named the same as the project, with the addition of environment suffixes (_development, _test, or _production), and you are using MySQL as your database, you do not have to create any database configuration. For example, had you named your database chapter3_development, you could have skipped this configuration step. However, it is not always realistic that you can give your database the same name as the Rails project name you choose. Often you may have to follow a company standard for naming your databases.

Because your database name is completely different than the application name, a small amount of database configuration is required. The code that configures the databases you will use with your Rails application is stored in a configuration file called database.yml.

In your chapter3 project directory, open the file config/database.yml and look for the section that contains this code:

development:
    adapter: mysql
    encoding: utf8
    database: chapter3_development
    username: root
    password:
    host: localhost

This is the default database configuration that Rails created when you generated the chapter3 application. Notice the default database name of chapter3_development. The default configuration also assumes that a root username is available with a blank password. The database is assumed to be running on the same computer that you are developing on, localhost.

You created a database named comic_books_development, so change this line:

database: chapter3_development

to use the name of your database:

database: comic_books_development

Also, if you used a username and password other than root, be sure to change those lines in the configuration.

You may be wondering about the different database environments that have been referred to. Rails supports the use of three separate environments for running your application in: the development, test, and production environments. The following section has a description of the three environments supported by Rails.

It is a good development practice to use different infrastructure environments when developing a Web application. Each environment should contain a unique database, Web server, and other external components that your application may require. Rails has built-in support for running your applications in three different environments. The environments supported by Rails are called development, test, and production. Each of these environments is described below:

You can specify the environment that you want your application to run in by editing the config/environment.rb file. The following line contained in that file specifies the environment that Rails will use:

# ENV['RAILS_ENV'] ||= 'production'

This line is commented out when you first create a Rails application. If you want to use this line to specify your environment, make sure you uncomment the line.

The databases for each environment are configured in the config/database.yml directory of your Rails application. You can also include environment specific configuration for your application by adding the appropriate configuration to the files contained in your application's config/environments directory. This directory contains a configuration file specific to each environment; development.rb, test.rb, and production.rb.

Most of the code that you will write in this book targets the development environment. However, when you get to Chapter 9, where testing is covered in detail, you'll see how the test environment is used.

The first time you run a migration, a new table that you may not recognize is also created in your schema. This table is called schema_info, and it keeps track of the current version of the database schema. The database schema is the current structure of the database, including the tables and columns that make up the database.

Each migration file that is run creates a new database schema version. The migration you ran is contained in the file 001_create_comic_books.rb. The 001 at the beginning of the filename is the migration number that corresponds to the database version number that will be created after this migration is run. Each migration that either you create or that is generated for you must have a unique three-digit number as the first three characters of the migration filename.

Migrations that are used to create database tables commonly contain the name of the table prepended with the word 'Create' following the three digit migration number, such as you see in the file name 001_create_comic_books.rb.

Using the rake command that you used to run the migration, you can also specify a specific schema version number to migrate up to or back to. When migrating to a version number that is lower than the current schema version number, each of the migrations past the version that you are migrating to will have their self.down methods executed.

The following rake command will migrate your database to a specific schema version number:

rake db:migrate VERSION=3

If your database had been at schema version 5, the self.down methods would be run on migrations 004 and 005. If your schema version was 1, the self.up methods would be run on migrations 002 and 003. When migrating down, such as from version 5 to version 3, the migration self.down methods are run in reverse order. For example, the 005 migration self.down method would run first, followed by the 004 self.down method. When migrating up, the self.up methods are run in numerical order.

There are a large number of built-in migration methods available within your migration files that you inherit from extending the ActiveRecord::Migration class. The most common methods that you will use to manipulate tables, columns, and indexes are summarized here. For a complete reference of available migration methods, go to http://api.rubyonrails.com/classes/ActiveRecord/Migration.html.

create_table(table_name, options)
drop_table(table_name)
rename_table(old_name, new_name)

create_table('tables', {'DEFAULT CHAR SET'=>'UTF-8'})

add_column(table_name, column_name, column_type, options)
rename_column(table_name, old_column_name, new_column_name)
remove_column(table_name, column_name)

{:default => 10}

add_index(table_name, column_name, options)
remove_index(table_name, options)

add_index(:comic_books,:writer,:unique=>true,:name=>'writer_
   idx')

remove_index(:comic_books,:name=>'writer_index')

In addition to modifying your database schema, you can also insert data into your database in a migration file. This makes it convenient to insert default data that your application might need to run. In this section, you can create a new migration and use it to add some default data into your comic_books database.

After going through the steps above, you could also migrate your database down by using the command:

rake db:migrate VERSION=1

This command would run the self.down method of your migration defined in 002_add_default_data.rb. You could then verify that the default data has been removed from your database.

Using a migration, you were able to create default data in your database. This is a common way of setting up default data for a Rails application. Remember that in a migration, you have full access to all of the code, including your models. Using the power of Ruby and your model layer, you can perform complex manipulations of your database using migrations.

There are several ways of creating new records using your Rails model classes. Each way uses a slightly different syntax, which you can see in this section.

One of the ways in which you can create new records in Rails is by instantiating a new object, setting its attributes, and then performing a save operation. The database operations necessary to insert a record into the database are completely encapsulated behind Active Record. Within your code, you simply deal with Ruby code and Ruby objects. This is in keeping with a good ORM implementation.

Here is an example of creating a record in the comic_books table that you created earlier in this chapter:

my_comic_book = ComicBook.new
my_comic_book.title = 'Captain America'
my_comic_book.issue = 20
my_comic_book.writer = 'Ed Brubaker'
my_comic_book.artist = 'Mike Perkins'
my_comic_book.publisher = 'Marvel'
my_comic_book.save

This save method writes this record to the comic_books database table. The new method can also accept a hash attribute for setting the attributes of the object instance you are creating. Let's add another record to the database using this style:

my_comic_book = ComicBook.new(
    :title => 'Captain America',
    :issue => 10,
    :writer => 'Ed Brubaker',
    :artist => 'Lee Weeks',
    :publisher => 'Marvel')
my_comic_book.save

Yet another way of using the new method is to pass it a block. Shown here, this technique is used to add another comic book to your database:

ComicBook.new do |book|
    book.title = 'Batman'
    book.issue = 18
    book.writer = 'Bill Finger'
    book.artist = 'Bob Kane'
    book.publisher = 'DC'
    book.save
end

Add one more comic book to your database using this technique, which creates a model and database record all in one line:

my_comic_book = ComicBook.create(
    :title => 'Superman & Batman',
    :issue => 2,
    :writer => 'John Byrne',
    :artist => 'John Byrne',
    :publisher => 'DC')

You may recall that this is the style you used to create a default database record in the second migration you wrote. The create method both instantiates the ComicBook instance and saves the record to the database. You can pass an array of hashes to the create method to create multiple objects and database records with one method call. An array of object instances will be returned from that call.

In all of these methods for creating a new object and record, Active Record automatically creates a new unique value and sets that as the id attribute while saving the record. After performing a save, you can then access the primary key as an attribute of the object, like this:

new_id = my_comic_book.id

Rails uses a combination of database introspection and metaprogramming to simplify your life as a developer when it comes to using your model classes and objects to read data from the database.

This section details how Rails helps you read the data that is stored in the database using your Rails model classes and built-in Rails methods. You can learn how to use column metadata, object attributes, and Rails find methods in the following subsections:

ComicBook.columns.each { |column|
    puts column.name
    puts column.null
    puts column.primary
    puts column.scale
    puts column.sql_type
    puts column.precision
    puts column.default
    puts column.type
    puts column.limit
}

the_title = comic_book.title

comic_book.methods.include? 'title'

begin
    my_comic_book = ComicBook.find(5)
rescue
    puts "Record Not Found"
end

ComicBook.find(:all,:conditions=>"title = 'Captain America'")

ComicBook.find(:first,:conditions=>"title = 'Captain America'")

ComicBook.find(:first,
              :conditions=>"title='Spiderman' and writer='Stan
   Lee'")

title = 'Spiderman'

writer = 'Stan Lee'
ComicBook.find(:first,
              :conditions=>["title=? and writer=?", title,
   writer])

ComicBook.find(:all,:order => 'issue DESC')

results = ComicBook.find_by_writer('Stan Lee')

results = ComicBook.find_by_writer_and_artist('Stan Lee','Steve
   Ditko')

results = ComicBook.find_by_writer_and_artist_and_title('Stan
   Lee','Steve Ditko','Spiderman'),

results = ComicBook.find_by_sql("SELECT * from comic_books WHERE
   issue>25")

If you've been reading along in this chapter up to this point, you've learned a lot of new techniques for creating and reading data into your application. Let's take a break from the Rails detailed coverage and try out some of what you've learned using the Rails Console.

By now, you've learned how to create and retrieve records from your database the Rails way. Next, you'll learn how to update and delete records.

After you've made changes to a model, you usually want to save those changes back to the database. With Rails, you update your database records just by working with your model classes. You do not have to write any SQL code to perform database updates.

Before you can update a record, you first need to retrieve it. Here you retrieve the first record in the database and change the issue number:

comic = ComicBook.find(:first)
comic.issue = 100
comic.save

This code is very simple. You retrieve the desired record from the database, update one or more attributes on the returned object, and then perform a save.

You can simplify the above code even further by using the update_attribute method, as shown here:

comic = ComicBook.find(:first)
comic.update_attribute:issue, 100

The update_attribute method allows you to set the value of an attribute and save the changed value back to the database in one step.

Rails has two methods for deleting objects from your database. These methods are slightly different in their behavior, and are as follows:

You can call either of these methods on any of your model object instances, such as your comic book instance:

comic.destroy

After calling the method, the record associated with the object is deleted from the database immediately.

Rails insulates you, the developer, from having to write SQL statements to access your database. However, there are times when you're debugging an application and you'd like to know what SQL Rails is using internally. For this purpose, the place to look is the development log file.

Open up the development.log file in the chapter3/log directory. You should see something similar to Figure 3.3.

Figure 3.3. The development.log file

The development.log file contains every SQL statement that is sent to the database server, including the details of how long it took to execute each SQL statement.

This level of logging would impact the performance of your production environment. You'd also end up with a very large log file that you'd somehow have to manage. For these reasons, you only get the SQL statement logging when you are in the development environment.

The one-to-one relationship is the simplest relationship, and can be modeled as shown in Figure 3.4. This type of relationship implies that there is a one-to-one correspondence between objects of one type and objects of another type. A one-to-zero-or-one relationship is actually modeled in the same way. In a one-to-zero-or-one relationship, one side of the relation can be empty.

The example used in Figure 3.4 considers books and their cover images. Assuming that the same image is never used on two different book covers, there is always a one-to-one relationship between books and cover images. Another way of saying this is that a book has one cover image, and a cover image belongs to one book.

Modeling this type of relationship in a Rails application requires a foreign key in one of the database tables and the use of some Rails DSL magic in your model classes. The foreign key should be used in the table that represents the zero-or-one side of the relationship. If it is a strict one-to-one relationship, one of the objects will usually seem to be naturally more dominant. The foreign key goes with the table of the less dominant object.

In the example of Figure 3.4, the cover_images table contains a foreign key book_id associating a cover_image with a specific book.

Figure 3.4. One-to-one relationship

The Book class uses the has_one method to create the relationship with a CoverImage object:

class Book < ActiveRecord::Base
    has_one:cover_image
end

class CoverImage < ActiveRecord::Base
    belongs_to:book
end

The many-to-one relationship is the most common type of data relationship. The simplest way of explaining a many-to-one relationship is with a picture. Figure 3.5 shows a many-to-one relationship that exists between books and chapters. A book represents the 'one' side of the relationship, and the chapters are the 'many' side of the relationship; one book contains many chapters.

Both chapters and books are models in your Rails application. In your database, each of the models is represented in a separate table. Databases use a concept called foreign keys to create a relationship between two tables. A foreign key is a column in one table that points to a row in a different table. In a Rails application, the foreign keys must be named with the singular form name of the table they are pointing to, followed by _id. For example, the foreign key column in the chapter's table would be named book_id. This column specifies the book that a chapter is contained within.

Figure 3.5. Many-to-one relationship

In addition to setting up your database schema in the correct way to model a many-to-one relationship, you also add special code to your model classes in a Rails application. Using the books and chapters example, your Book class would look like this:

class Book < ActiveRecord::Base
    has_many:chapters
end

The has_many method indicates that a book has many chapters.

chapter_count = book.chapters.size

class Chapter < ActiveRecord::Base
    belongs_to:book
end

In a many-to-many relationship, each side of the relationship can point to more than one related object. Again, the best way to illustrate this kind of relationship is through a picture. Let's look at the many-to-many relationship in Figure 3.6. This example uses a Book and a Store model. A store contains many books, and thus it's easy to understand this 'many' side of the relationship. Looking at the relationship from the other direction, a book is usually sold in many different stores. Because both objects can be related to many of the other objects, you have a many-to-many relationship.

In a many-to-one relationship, a foreign key was used to model the relationship in the database. A many-to-many relationship must be modeled in the database using a slightly more complex technique. You use a relationship join table to model the many-to-many relationship. In Figure 3.6 this join table is shown as books_stores. In order for Rails to recognize the table and correctly build the association, this join table should be named with the names of the two related tables in alphabetical order and separated by an underscore. Thus in this case, you end up with the table named books_stores. You would create this table using a migration, just as you create regular model object tables. However, you do not need to generate a model class to represent this table.

Figure 3.6. Many-to-many relationship

As with the other Rails recognized relationships, you also have to add some code to each of the related models. The method call that you will add to each model is the same in this case. It is the has_and_belongs_to_many method. You will often see this shortened as HABTM in discussions online. So following through with the example shown in Figure 3.6, you would add this method to each of the Book and Store classes.

class Book < ActiveRecord::Base
    has_and_belongs_to_many:stores
end

class Store < ActiveRecord::Base
    has_and_belongs_to_many:books
end

store_count = book.stores.size

book_count = store.books.size

Active Record uses a database technique called single table inheritance to support inheritance in your model classes. With single table inheritance, a class and all of its descendents use the same database table. For example, the ComicBook model that you've been working with in this chapter could have extended a model class called Book, because a comic book is a type of book. Your application might also work with other types of books, such as text books. You might have a TextBook model which also extends the Book model. With single table inheritance, books, comic books, and text books would be stored in the same table. See Figure 3.7 for an example of how the classes and database should be laid out.

Figure 3.7. Single table inheritance

Notice that the common table is given the plural name of the base class. In this case, the table is named books. The books table contains a column named type, which specifies for a particular record whether that record is a text book or a comic book. Active Record automatically manages the type column.

Your model classes would be defined like this:

class ComicBook < Book
end

class TextBook < Book
end

class Book < ActiveRecord::Base
end

If you perform a query using the Book class, it returns both text books and comic books. A query using the ComicBook class returns only comic books and a query using the TextBook class returns only text books, as expected.

If you ever need to see the type field, you cannot access it using book.type because the type field is a class attribute. However, you can access it from your objects like this:

book[:type]

The above line would return the type of the object, either ComicBook or TextBook.

Composition is a design pattern in which you have one class composed of several other classes. Note that this is not the same as inheritance, in which a subclass extends a base class. With composition, you have a main class and one or more component classes. This design pattern is also referred to as aggregation.

Rails implements the composition pattern using one table that is mapped to multiple classes. Consider the example of a Book that is composed of a Publisher. Figure 3.8 shows how the classes and database table would be laid out. As you can see, the books table contains columns for attributes that exist in both the Book and Publisher classes. You would implement the composition in your Book model class like this:

class Book < ActiveRecord::Base
    composed_of:publisher,:class_name => "Publisher",
               :mapping => [[:publisher_name,:name],
                                [:publisher_country,:country]]
End

Figure 3.8. Rails implementation of the Composition Pattern

The first parameter to composed_of is the name that the component class is referred to by the main class. In this example, because the first parameter to composed_of and the component class name are the same, you could have eliminated the :class_name parameter. By default, Rails looks for a class that contains the same name as the first parameter to composed_of.

The :class_name parameter allows you to override the Rails default and use a different name from that of the class as the first parameter. For example, you could have used this line:

composed_of:publisher_info,:class_name => "Publisher",

The second parameter to composed_of specifies the attribute mappings. The :mapping array associates columns in the books database with attributes in the Publisher class. For the mapping in this example, the publisher_name column in the books table is mapped to the name attribute of the Publisher class, and the publisher_country column is mapped to the country attribute of the Publisher class.

You also have to add some code to your component class, Publisher. Publisher would look like this:

class Publisher
    def initialize(name, country)
        @ name = name
        @ country = country
    end

    attr_reader: name,: country
end

You must create an initialize method that contains a parameter for each attribute that the component represents. Within the initialize method, you have to create instance attributes for each of the component attributes.

Rails adds accessors to the main class for the component class and each of its attributes. You could access the Publisher object from an instance of the Book class using: book.publisher. You can also set the publisher of a book using this code:

book.publisher = Publisher.new('', '', '')

You access each of the attributes in the component class through the parent class attribute of the main class. From an instance of the Book class, you would access the Publisher attributes like this:

pub_name = book.publisher. name
pub_country = abook.publisher. country

Composition is often used when you have a class that you want to use across many models. An often-cited example is the case of a Person and Address class. A Person is composed of an Address. In this example, you might want to also use the Address class across other models. The Business and Museum classes might also be composed of an Address. Employing composition in this example would save you from having to repeat the attributes and behavior contained in the Address model in all of the models that are composed with it.

Many applications that you write will require the use of database transactions. Transactions are a way of grouping database actions together, such that they either all execute as expected, or none of them execute in the case of an error.

Rails supports transactions using a transaction class method that is available on all model classes that extend ActiveRecord::Base. A typical example of when transactions are required is when you are working with bank accounts. When you transfer money from one account to another, that process can be broken down into the following actions:

If the first action, subtracting the money from the 'from' account succeeded, but the second action of adding the money to the 'to' account failed, you would have many unhappy customers if your application did not make use of transactions. If both of these actions were wrapped in a transaction, a failure in the second action would cause the first action to be undone, or rolled back. A roll back is a database term for undoing an action that was performed on the database.

Using this example, in your Rails application, you would likely have a class named Account. The Account class would have a transfer method implemented as follows:

def transfer(from, to, amount)
    Account.transaction do
        from.withdraw(amount)
        to.deposit(amount)
    end
end

Now if any failures occur in either of the method calls contained in the block that begins with the Account.transaction do line, all of the database actions will be rolled back. Therefore, either both the withdrawal and deposit actions succeed, or they are both rolled back. This is exactly the behavior that you were seeking.