5.1. Creating a New Rails Application

If you were to create a new ASP.NET application, you would typically reach for Visual Studio or its free counterpart Visual Web Developer 2008 Express Edition, in order to produce a new ASP.NET website. The solution and project generated would essentially be an almost empty container for the items that you'd add as you developed the application.

With Rails you reach for the command line and invoke the rails command, unless you are using one of the available IDEs that does that behind the scenes for you. Unlike Visual Studio, this command generates several folders and files that act as the skeleton of your application.

5.1.1. The rails Command

You can use the rails command to create your blog application:

C:projects> rails blog

This creates a blog directory in the current one (C:projects in this case) and also prints a list of directories and files that are generated, as shown in Figure 5-1.

Figure 5.1. Figure 5-1

You use cd to step into the blog directory that was just generated by the rails command:

C:projects> cd blog

The directory structure is shown in Figure 5-2. In this chapter you get to interact with several of these directories, in particular with app, where most of the application resides, and config, where the configuration of the application is found. The next chapter presents a more systematic explanation of all the remaining folders.

Figure 5.2. Figure 5-2

5.1.2. configdatabase.yml

The database credentials in a Rails application are stored in configdatabase.yml by default. Listing 5-1 shows the one generated by the previous rails command (available for download as listing0501.yml).

Example 5.1. Default configdatabase.yml for SQLite3

# SQLite version 3.x
#   gem install sqlite3-ruby (not necessary on OS X Leopard)
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

As you can see this is not XML but a very readable YAML (recursive acronym for YAML Ain't a Markup Language) file. Ruby ships with support for reading and writing YAML files and this format is often favored over XML in the Ruby and Rails communities.

You'll also notice that adapter, database, and timeout are provided for each of the three environments: development, test, and production. These three environments are independent of each other, so in theory you could use SQLite3 for development, SQL Server for production, and MySQL for testing. Of course this doesn't generally make much sense and it's not recommended, but it illustrates how each environment can be treated as a separate world independently from the others. Furthermore, it clearly highlights how Rails' database abstraction allows you to write Ruby code while all the heavy lifting is done for you, regardless of what database environment you ultimately end up using.

Depending on whether you're in development mode, production mode, or test mode, Rails will employ the right database and other supported options, as specified (for example, the 5 seconds timeout or the size of the connection pool). In this particular case, given that sqlite3 is Rails' default adapter, there isn't very much to specify, because you don't have to provide a username and password, nor the details to reach a remote host that is running your databases.

Had you decided to employ MySQL instead, you would have run the rails command with the -d option and passed the name of the adapter required (that is, -d mysql). Even though SQLite, MySQL, and PostgreSQL are the only databases for which the adapter ships directly with Rails, the -d option currently accepts the following adapters: mysql, sqlite2, sqlite3, postgresql, oracle, frontbase, and ibm_db (for DB2). If you are using SQL Server, for example, you will have to skip the -d option and manually modify the database.yml.

Running rails blog -d mysql would have generated the database.yml as shown in Listing 5-2 (available for download as listing0502.yml) for you.

Listing 5-2 strips all the comments from the file for improved clarity on the printed page.

Example 5.2. Default configdatabase.yml for MySQL

development:
  adapter: mysql
  encoding: utf8
  database: blog_development
  pool: 5
  username: root
  password:
  host: localhost

test:
  adapter: mysql
  encoding: utf8
  database: blog_test
  pool: 5
  username: root
  password:
  host: localhost

production:
  adapter: mysql
  encoding: utf8
  database: blog_production
  pool: 5
  username: root
  password:
  host: localhost

The database name for each of the three environments is automatically generated based on the name of the application and the environment at hand. The default host name is localhost, and in the specific case of MySQL there is an encoding parameter set to utf-8 to support internationalization.

If you were using a remote MySQL database, you could specify the host IP or name and optionally its port number.

Compare this approach with the option of adding a connection string to a Web.config XML file and you'll start to realize how Rails consistently tries to make things easy for the developer from the beginning. You provide the user credentials, specify the database and its location, and you're set. In this case, using SQLite3 practically means that you don't even have to touch the database.ymlfile at all.

5.1.3. Creating Databases

Rails generates and populates a configuration file for your databases, but it doesn't automatically create the actual databases for you. In order to create the databases you have two options. You could create them independently from Rails, for example, by using the sqlite3 command for SQLite3 databases, or SQL Server Management Studio for SQL Server databases. This approach works, but Rails provides a handier option when the databases that need to be created are local to the machine that's running Rails. You can create local databases using a Rake task.

Rake is a build tool, just like Microsoft nmake and NAnt. It allows you to define a series of tasks in Ruby that perform certain actions for you. As you can imagine, Rails ships with a whole set of useful Rake tasks to help out while developing applications. To create all the local databases specified in the database.yml file, run the following:

C:projectslog> rake db:create:all

Similarly, you can drop all the local databases with rake db:drop:all. If you want to create or drop the database for a specific environment only, use rake db:create and rake db:drop, respectively. In Rails, the default environment is development, so if you execute those two Rake tasks without specifying an argument, they will create and drop the local development database, respectively. If you want to explicitly specify that, say, the production database should be created or dropped (be careful with dropping actual production databases), you can pass a RAILS_ENV=production argument to the tasks (for example, rake db:create RAILS_ENV=production).

To display a complete list of Rake tasks that are available in a given Rails application, you can run rake -T. You can also limit the list of tasks to those that contain a given word as shown here:

C:projectslog> rake -T notes
(in C:/projects/blog)
rake notes           # Enumerate all annotations
rake notes:custom    # Enumerate a custom annotation, specify with ANNOTATI...
rake notes:fixme     # Enumerate all FIXME annotations
rake notes:optimize  # Enumerate all OPTIMIZE annotations
rake notes:todo      # Enumerate all TODO annotations

By the way, the tasks in the output are used to retrieve all the FIXME, OPTIMIZE, and TODO or custom comments embedded in your Rails application's code, in a similar manner to how you'd use the Task List in Visual Studio.