1. Introduction

Welcome to Ruby on Rails! In this guide, we'll walk through the core concepts of building web applications with Rails. You don't need any experience with Rails to follow along with this guide.

Rails is a web framework built for the Ruby programming language. Rails takes advantage of many features of Ruby so we strongly recommend learning the basics of Ruby so that you understand some of the basic terms and vocabulary you will see in this tutorial.

• Official Ruby Programming Language website
• List of Free Programming Books

2. Rails Philosophy

Rails is a web application development framework written in the Ruby programming language. It is designed to make programming web applications easier by making assumptions about what every developer needs to get started. It allows you to write less code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that it makes web application development more fun.

Rails is opinionated software. It makes the assumption that there is a "best" way to do things, and it's designed to encourage that way - and in some cases to discourage alternatives. If you learn "The Rails Way" you'll probably discover a tremendous increase in productivity. If you persist in bringing old habits from other languages to your Rails development, and trying to use patterns you learned elsewhere, you may have a less happy experience.

The Rails philosophy includes two major guiding principles:

• Don't Repeat Yourself: DRY is a principle of software development which states that "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system". By not writing the same information over and over again, our code is more maintainable, more extensible, and less buggy.
• Convention Over Configuration: Rails has opinions about the best way to do many things in a web application, and defaults to this set of conventions, rather than require that you define them yourself through endless configuration files.

3. Creating a New Rails App

We're going to build a project called store - a simple e-commerce app that demonstrates several of Rails' built-in features.

3.1. Prerequisites

For this project, you will need:

• Ruby 3.2 or newer
• Rails 8.0.0 or newer
• A code editor

Follow the Install Ruby on Rails Guide if you need to install Ruby and/or Rails.

Let's verify the correct version of Rails is installed. To display the current version, open a terminal and run the following. You should see a version number printed out:

$ rails --version
Rails 8.0.0

The version shown should be Rails 8.0.0 or higher.

3.2. Creating Your First Rails App

Rails comes with several commands to make life easier. Run rails --help to see all of the commands.

rails new generates the foundation of a fresh Rails application for you, so let's start there.

To create our store application, run the following command in your terminal:

$ rails new store

After your new application is created, switch to its directory:

$ cd store

3.3. Directory Structure

Let's take a quick glance at the files and directories that are included in a new Rails application. You can open this folder in your code editor or run ls -la in your terminal to see the files and directories.

3.4. Model-View-Controller Basics

Rails code is organized using the Model-View-Controller (MVC) architecture. With MVC, we have three main concepts where the majority of our code lives:

• Model - Manages the data in your application. Typically, your database tables.
• View - Handles rendering responses in different formats like HTML, JSON, XML, etc.
• Controller - Handles user interactions and the logic for each request.

Now that we've got a basic understanding of MVC, let's see how it's used in Rails.

4. Hello, Rails!

Let's start easy and boot up our Rails server for the first time.

In your terminal, run the following command in the store directory:

$ bin/rails server

This will start up a web server called Puma that will serve static files and your Rails application:

=> Booting Puma
=> Rails 8.0.0 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 6.4.3 (ruby 3.3.5-p100) ("The Eagle of Durango")
*  Min threads: 3
*  Max threads: 3
*  Environment: development
*          PID: 12345
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

To see your Rails application, open http://localhost:3000 in your browser. You will see the default Rails welcome page:

It works!

This page is the smoke test for a new Rails application, ensuring that everything is working behind the scenes to serve a page.

To stop the Rails server anytime, press Ctrl-C in your terminal.

4.1. Autoloading in Development

Developer happiness is a cornerstone philosophy of Rails and one way of achieving this is with automatic code reloading in development.

Once you start the Rails server, new files or changes to existing files are detected and automatically loaded or reloaded as necessary. This allows you to focus on building without having to restart your Rails server after every change.

You may also notice that Rails applications rarely use require statements like you may have seen in other programming languages. Rails uses naming conventions to require files automatically so you can focus on writing your application code.

See Autoloading and Reloading Constants for more details.

5. Creating a Database Model

Active Record is a feature of Rails that maps relational databases to Ruby code. It helps generate the structured query language (SQL) for interacting with the database like creating, updating, and deleting tables and records. Our application is using SQLite which is the default for Rails.

Let's start by adding a database table to our Rails application to add products to our simple e-commerce store.

$ bin/rails generate model Product name:string

This command tells Rails to generate a model named Product which has a name column and type of string in the database. Later on, you'll learn how to add other column types.

You'll see the following in your terminal:

      invoke  active_record
      create    db/migrate/20240426151900_create_products.rb
      create    app/models/product.rb
      invoke    test_unit
      create      test/models/product_test.rb
      create      test/fixtures/products.yml

This command does several things. It creates...

1. A migration in the db/migrate folder.
2. An Active Record model in app/models/product.rb.
3. Tests and test fixtures for this model.

5.1. Database Migrations

A migration is a set of changes we want to make to our database.

By defining migrations, we're telling Rails how to change the database to add, change, or remove tables, columns or other attributes of our database. This helps keep track of changes we make in development (only on our computer) so they can be deployed to production (live, online!) safely.

In your code editor, open the migration Rails created for us so we can see what the migration does. This is located in db/migrate/_create_products.rb:

class CreateProducts < ActiveRecord::Migration[8.0]
  def change
    create_table :products do |t|
      t.string :name

      t.timestamps
    end
  end
end

This migration is telling Rails to create a new database table named products.

The create_table block then defines which columns and types should be defined in this database table.

t.string :name tells Rails to create a column in the products table called name and set the type as string.

t.timestamps is a shortcut for defining two columns on your models: created_at:datetime and updated_at:datetime. You'll see these columns on most Active Record models in Rails and they are automatically set by Active Record when creating or updating records.

5.2. Running Migrations

Now that you have defined what changes to make to the database, use the following command to run the migrations:

$ bin/rails db:migrate

This command checks for any new migrations and applies them to your database. Its output looks like this:

== 20240426151900 CreateProducts: migrating ===================================
-- create_table(:products)
   -> 0.0030s
== 20240426151900 CreateProducts: migrated (0.0031s) ==========================

6. Rails Console

Now that we have created our products table, we can interact with it in Rails. Let's try it out.

For this, we're going to use a Rails feature called the console. The console is a helpful, interactive tool for testing our code in our Rails application.

$ bin/rails console

You will be presented with a prompt like the following:

Loading development environment (Rails 8.0.0)
store(dev)>

Here we can type code that will be executed when we hit Enter. Let's try printing out the Rails version:

store(dev)> Rails.version
=> "8.0.0"

It works!

7. Active Record Model Basics

When we ran the Rails model generator to create the Product model, it created a file at app/models/product.rb. This file creates a class that uses Active Record for interacting with our products database table.

class Product < ApplicationRecord
end

You might be surprised that there is no code in this class. How does Rails know what defines this model?

When the Product model is used, Rails will query the database table for the column names and types and automatically generate code for these attributes. Rails saves us from writing this boilerplate code and instead takes care of it for us behind the scenes so we can focus on our application logic instead.

Let's use the Rails console to see what columns Rails detects for the Product model.

Run:

store(dev)> Product.column_names

And you should see:

=> ["id", "name", "created_at", "updated_at"]

Rails asked the database for column information above and used that information to define attributes on the Product class dynamically so you don't have to manually define each of them. This is one example of how Rails makes development a breeze.

7.1. Creating Records

We can instantiate a new Product record with the following code:

store(dev)> product = Product.new(name: "T-Shirt")
=> #<Product:0x000000012e616c30 id: nil, name: "T-Shirt", created_at: nil, updated_at: nil>

The product variable is an instance of Product. It has not been saved to the database, and so does not have an ID, created_at, or updated_at timestamps.

We can call save to write the record to the database.

store(dev)> product.save
  TRANSACTION (0.1ms)  BEGIN immediate TRANSACTION /*application='Store'*/
  Product Create (0.9ms)  INSERT INTO "products" ("name", "created_at", "updated_at") VALUES ('T-Shirt', '2024-11-09 16:35:01.117836', '2024-11-09 16:35:01.117836') RETURNING "id" /*application='Store'*/
  TRANSACTION (0.9ms)  COMMIT TRANSACTION /*application='Store'*/
=> true

When save is called, Rails takes the attributes in memory and generates an INSERT SQL query to insert this record into the database.

Rails also updates the object in memory with the database record id along with the created_at and updated_at timestamps. We can see that by printing out the product variable.

store(dev)> product
=> #

Similar to save, we can use create to instantiate and save an Active Record object in a single call.

store(dev)> Product.create(name: "Pants")
  TRANSACTION (0.1ms)  BEGIN immediate TRANSACTION /*application='Store'*/
  Product Create (0.4ms)  INSERT INTO "products" ("name", "created_at", "updated_at") VALUES ('Pants', '2024-11-09 16:36:01.856751', '2024-11-09 16:36:01.856751') RETURNING "id" /*application='Store'*/
  TRANSACTION (0.1ms)  COMMIT TRANSACTION /*application='Store'*/
=> #

7.2. Querying Records

We can also look up records from the database using our Active Record model.

To find all the Product records in the database, we can use the all method. This is a class method, which is why we can use it on Product (versus an instance method that we would call on the product instance, like save above).

store(dev)> Product.all
  Product Load (0.1ms)  SELECT "products".* FROM "products" /* loading for pp */ LIMIT 11 /*application='Store'*/
=> [#,
 #]

This generates a SELECT SQL query to load all records from the products table. Each record is automatically converted into an instance of our Product Active Record model so we can easily work with them from Ruby.

7.3. Filtering & Ordering Records

What if we want to filter the results from our database? We can use where to filter records by a column.

store(dev)> Product.where(name: "Pants")
  Product Load (1.5ms)  SELECT "products".* FROM "products" WHERE "products"."name" = 'Pants' /* loading for pp */ LIMIT 11 /*application='Store'*/
=> [#]

This generates a SELECT SQL query but also adds a WHERE clause to filter the records that have a name matching "Pants". This also returns an ActiveRecord::Relation because multiple records may have the same name.

We can use order(name: :asc) to sort records by name in ascending alphabetical order.

store(dev)> Product.order(name: :asc)
  Product Load (0.3ms)  SELECT "products".* FROM "products" /* loading for pp */ ORDER BY "products"."name" ASC LIMIT 11 /*application='Store'*/
=> [#,
 #]

7.4. Finding Records

What if we want to find one specific record?

We can do this by using the find class method to look up a single record by ID. Call the method and pass in the specific ID by using the following code:

store(dev)> Product.find(1)
  Product Load (0.2ms)  SELECT "products".* FROM "products" WHERE "products"."id" = 1 LIMIT 1 /*application='Store'*/
=> #

This generates a SELECT query but specifies a WHERE for the id column matching the ID of 1 that was passed in. It also adds a LIMIT to only return a single record.

This time, we get a Product instance instead of an ActiveRecord::Relation since we're only retrieving a single record from the database.

7.5. Updating Records

Records can be updated in 2 ways: using update or assigning attributes and calling save.

We can call update on a Product instance and pass in a Hash of new attributes to save to the database. This will assign the attributes, run validations, and save the changes to the database in one method call.

store(dev)> product = Product.find(1)
store(dev)> product.update(name: "Shoes")
  TRANSACTION (0.1ms)  BEGIN immediate TRANSACTION /*application='Store'*/
  Product Update (0.3ms)  UPDATE "products" SET "name" = 'Shoes', "updated_at" = '2024-11-09 22:38:19.638912' WHERE "products"."id" = 1 /*application='Store'*/
  TRANSACTION (0.4ms)  COMMIT TRANSACTION /*application='Store'*/
=> true

This updated the name of the "T-Shirt" product to "Shoes" in the database. Confirm this by running Product.all again.

store(dev)> Product.all

You will see two products: Shoes and Pants.

  Product Load (0.3ms)  SELECT "products".* FROM "products" /* loading for pp */ LIMIT 11 /*application='Store'*/
=>
[#<Product:0x000000012c0f7300
  id: 1,
  name: "Shoes",
  created_at: "2024-12-02 20:29:56.303546000 +0000",
  updated_at: "2024-12-02 20:30:14.127456000 +0000">,
 #
  id: 2,
  name: "Pants",
  created_at: "2024-12-02 20:30:02.997261000 +0000",
  updated_at: "2024-12-02 20:30:02.997261000 +0000">]

Alternatively, we can assign attributes and call save when we're ready to validate and save changes to the database.

Let's change the name "Shoes" back to "T-Shirt".

store(dev)> product = Product.find(1)
store(dev)> product.name = "T-Shirt"
=> "T-Shirt"
store(dev)> product.save
  TRANSACTION (0.1ms)  BEGIN immediate TRANSACTION /*application='Store'*/
  Product Update (0.2ms)  UPDATE "products" SET "name" = 'T-Shirt', "updated_at" = '2024-11-09 22:39:09.693548' WHERE "products"."id" = 1 /*application='Store'*/
  TRANSACTION (0.0ms)  COMMIT TRANSACTION /*application='Store'*/
=> true

7.6. Deleting Records

The destroy method can be used to delete a record from the database.

store(dev)> product.destroy
  TRANSACTION (0.1ms)  BEGIN immediate TRANSACTION /*application='Store'*/
  Product Destroy (0.4ms)  DELETE FROM "products" WHERE "products"."id" = 1 /*application='Store'*/
  TRANSACTION (0.1ms)  COMMIT TRANSACTION /*application='Store'*/
=> #

This deleted the T-Shirt product from our database. We can confirm this with Product.all to see that it only returns Pants.

store(dev)> Product.all
  Product Load (1.9ms)  SELECT "products".* FROM "products" /* loading for pp */ LIMIT 11 /*application='Store'*/
=>
[#<Product:0x000000012abde4c8
  id: 2,
  name: "Pants",
  created_at: "2024-11-09 22:33:19.638912000 +0000",
  updated_at: "2024-11-09 22:33:19.638912000 +0000">]

7.7. Validations

Active Record provides validations which allows you to ensure data inserted into the database adheres to certain rules.

Let's add a presence validation to the Product model to ensure that all products must have a name.

class Product < ApplicationRecord
  validates :name, presence: true
end

You might remember that Rails automatically reloads changes during development. However, if the console is running when you make updates to the code, you'll need to manually refresh it. So let's do this now by running 'reload!'.

store(dev)> reload!
Reloading...

Let's try to create a Product without a name in the Rails console.

store(dev)> product = Product.new
store(dev)> product.save
=> false

This time save returns false because the name attribute wasn't specified.

Rails automatically runs validations during create, update, and save operations to ensure valid input. To see a list of errors generated by validations, we can call errors on the instance.

store(dev)> product.errors
=> #<ActiveModel::Errors [#<ActiveModel::Error attribute=name, type=blank, options={}>]>

This returns an ActiveModel::Errors object that can tell us exactly which errors are present.

It also can generate friendly error messages for us that we can use in our user interface.

store(dev)> product.errors.full_messages
=> ["Name can't be blank"]

Now let's build a web interface for our Products.

We are done with the console for now, so you can exit out of it by running exit.

8. A Request's Journey Through Rails

To get Rails saying "Hello", you need to create at minimum a route, a controller with an action, and a view. A route maps a request to a controller action. A controller action performs the necessary work to handle the request, and prepares any data for the view. A view displays data in a desired format.

In terms of implementation: Routes are rules written in a Ruby DSL (Domain-Specific Language). Controllers are Ruby classes, and their public methods are actions. And views are templates, usually written in a mixture of HTML and Ruby.

That's the short of it, but we’re going to walk through each of these steps in more detail next.

9. Routes

In Rails, a route is the part of the URL that determines how an incoming HTTP request is directed to the appropriate controller and action for processing. First, let's do a quick refresher of URLs and HTTP Request methods.

9.1. Parts of a URL

Let's examine the different parts of a URL:

http://example.org/products?sale=true&sort=asc

In this URL, each part has a name:

• https is the protocol
• example.org is the host
• /products is the path
• ?sale=true&sort=asc are the query parameters

9.2. HTTP Methods and Their Purpose

HTTP requests use methods to tell a server what action it should perform for a given URL. Here are the most common methods:

• A GET request tells the server to retrieve the data for a given URL (e.g., loading a page or fetching a record).
• A POST request will submit data to the URL for processing (usually creating a new record).
• A PUT or PATCH request submits data to a URL to update an existing record.
• A DELETE request to a URL tells the server to delete a record.

9.3. Rails Routes

A route in Rails refers to a line of code that pairs an HTTP Method and a URL path. The route also tells Rails which controller and action should respond to a request.

To define a route in Rails, let's go back to your code editor and add the following route to config/routes.rb

Rails.application.routes.draw do
  get "/products", to: "products#index"
end

This route tells Rails to look for GET requests to the /products path. In this example, we specified "products#index" for where to route the request.

When Rails sees a request that matches, it will send the request to the ProductsController and the index action inside of that controller. This is how Rails will process the request and return a response to the browser.

You'll notice that we don't need to specify the protocol, domain, or query params in our routes. That's basically because the protocol and domain make sure the request reaches your server. From there, Rails picks up the request and knows which path to use for responding to the request based on what routes are defined. The query params are like options that Rails can use to apply to the request, so they are typically used in the controller for filtering the data.

Let's look at another example. Add this line after the previous route:

post "/products", to: "products#create"

Here, we've told Rails to take POST requests to "/products" and process them with the ProductsController using the create action.

Routes may also need to match URLs with certain patterns. So how does that work?

get "/products/:id", to: "products#show"

This route has :id in it. This is called a parameter and it captures a portion of the URL to be used later for processing the request.

If a user visits /products/1, the :id param is set to 1 and can be used in the controller action to look up and display the Product record with an ID of 1. /products/2 would display Product with an ID of 2 and so on.

Route parameters don't have to be Integers, either.

For example, you could have a blog with articles and match /blog/hello-world with the following route:

get "/blog/:title", to: "blog#show"

Rails will capture hello-world out of /blog/hello-world and this can be used to look up the blog post with the matching title.

9.3.1. CRUD Routes

There are 4 common actions you will generally need for a resource: Create, Read, Update, Delete (CRUD). This translates to 8 typical routes:

• Index - Shows all the records
• New - Renders a form for creating a new record
• Create - Processes the new form submission, handling errors and creating the record
• Show - Renders a specific record for viewing
• Edit - Renders a form for updating a specific record
• Update (full) - Handles the edit form submission, handling errors and updating the entire record, and typically triggered by a PUT request.
• Update (partial) - Handles the edit form submission, handling errors and updating specific attributes of the record, and typically triggered by a PATCH request.
• Destroy - Handles deleting a specific record

We can add routes for these CRUD actions with the following:

get "/products", to: "products#index"

get "/products/new", to: "products#new"
post "/products", to: "products#create"

get "/products/:id", to: "products#show"

get "/products/:id/edit", to: "products#edit"
patch "/products/:id", to: "products#update"
put "/products/:id", to: "products#update"

delete "/products/:id", to: "products#destroy"

9.3.2. Resource Routes

Typing out these routes every time is redundant, so Rails provides a shortcut for defining them. To create all of the same CRUD routes, replace the above routes with this single line:

resources :products

9.4. Routes Command

Rails provides a command that displays all the routes your application responds to.

In your terminal, run the following command.

$ bin/rails routes

You'll see this in the output which are the routes generated by resources :products

                                  Prefix Verb   URI Pattern                                                                                       Controller#Action
                                products GET    /products(.:format)                                                                               products#index
                                         POST   /products(.:format)                                                                               products#create
                             new_product GET    /products/new(.:format)                                                                           products#new
                            edit_product GET    /products/:id/edit(.:format)                                                                      products#edit
                                 product GET    /products/:id(.:format)                                                                           products#show
                                         PATCH  /products/:id(.:format)                                                                           products#update
                                         PUT    /products/:id(.:format)                                                                           products#update
                                         DELETE /products/:id(.:format)                                                                           products#destroy

You'll also see routes from other built-in Rails features like health checks.

10. Controllers & Actions

Now that we've defined routes for Products, let's implement the controller and actions to handle requests to these URLs.

This command will generate a ProductsController with an index action. Since we've already set up routes, we can skip that part of the generator using a flag.

$ bin/rails generate controller Products index --skip-routes
      create  app/controllers/products_controller.rb
      invoke  erb
      create    app/views/products
      create    app/views/products/index.html.erb
      invoke  test_unit
      create    test/controllers/products_controller_test.rb
      invoke  helper
      create    app/helpers/products_helper.rb
      invoke    test_unit

This command generates a handful of files for our controller:

• The controller itself
• A views folder for the controller we generated
• A view file for the action we specified when generating the controller
• A test file for this controller
• A helper file for extracting logic in our views

Let's take a look at the ProductsController defined in app/controllers/products_controller.rb. It looks like this:

class ProductsController < ApplicationController
  def index
  end
end

The index method here is an Action. Even though it's an empty method, Rails will default to rendering a template with the matching name.

The index action will render app/views/products/index.html.erb. If we open up that file in our code editor, we'll see the HTML it renders.

Products#index
Find me in app/views/products/index.html.erb

10.1. Making Requests

Let's see this in our browser. First, run bin/rails server in your terminal to start the Rails server. Then open http://localhost:3000 and you will see the Rails welcome page.

If we open http://localhost:3000/products in the browser, Rails will render the products index HTML.

Our browser requested /products and Rails matched this route to products#index. Rails sent the request to the ProductsController and called the index action. Since this action was empty, Rails rendered the matching template at app/views/products/index.html.erb and returned that to our browser. Pretty cool!

If we open config/routes.rb, we can tell Rails the root route should render the Products index action by adding this line:

root "products#index"

Now when you visit http://localhost:3000, Rails will render Products#index.

10.2. Instance Variables

Let's take this a step further and render some records from our database.

In the index action, let's add a database query and assign it to an instance variable. Rails uses instance variables (variables that start with an @) to share data with the views.

class ProductsController < ApplicationController
  def index
    @products = Product.all
  end
end

In app/views/products/index.html.erb, we can replace the HTML with this ERB:

<%= debug @products %>

ERB is short for Embedded Ruby and allows us to execute Ruby code to dynamically generate HTML with Rails. The <%= %> tag tells ERB to execute the Ruby code inside and output the return value. In our case, this takes @products, converts it to YAML, and outputs the YAML.

Now refresh http://localhost:3000/ in your browser and you'll see that the output has changed. What you're seeing is the records in your database being displayed in YAML format.

The debug helper prints out variables in YAML format to help with debugging. For example, if you weren't paying attention and typed singular @product instead of plural @products, the debug helper could help you identify that the variable was not set correctly in the controller.

Let's update app/views/products/index.html.erb to render all of our product names.

Products

 id="products">
  <% @products.each do |product| %>
    

      <%= product.name %>
    
  <% end %>