DEV Community: Levi

A Simple Git Branch Workflow

Levi — Sat, 04 Jan 2020 23:01:41 +0000

Why?

Git is the preeminent tool for version control–that is, keeping track of and managing changes. This post is about implementing a simple but powerful workflow for managing and tracking the changes of a project as it grows and matures. A branching workflow allows us to carefully make and track changes to our project without risking the integrity of its core.

Version control gives us a better handle on the animal of our code base. Every project warrants a repository, an observed and organized container for code. If you're serious about grooming a project that lasts, you owe it to yourself to use Git. For the purposes of this illustration, we'll use Github as the example of an online host for Git.

How

Getting Started

New projects must be started either locally or with a new repository on Github. This new repository may be either initialized with files or linked with an existing local directory. Mind the checkbox labelled "Initialize with a README" when creating a new repository (here on out referred to as a repo).

If you have already started a project on your computer you will be "importing an existing repository," so take Github's advice and do not check this box. Checking the box will make it more complicated to link your local directory with the remote repo. Instead, "push [this] existing repository on the command line" by opening a terminal window, moving into the project's directory, and executing the following three lines:

$ git init
$ git remote add origin git@github.com:USERNAME/REPO-NAME.git
$ git push -u origin master

git init initializes the local directory as a new, empty git repo ($ denotes that we're executing this command in the terminal). This command generates an invisible .git file and endows the directory space with all the powers that Git affords. git remote add adds a remote (i.e. server) of the name origin at the address git@github.com:USERNAME/REPO-NAME.git. This command links the local repository to a server that will also host the repository. git push -u origin master pushes, or uploads, the contents in the master branch of the directory to the origin server. -u sets this remote repository as the default upstream reference, meaning origin will be the default remote repository from which things are pulled and to which things are pushed.

If you're starting your project from scratch and have no local work, feel free to check the box and have the resulting generated README.md serve as your first project file!

Below is an illustration of the state of our project. The shapes with dashed borders represent the project on the remote repository, while the solid-bordered shapes represent the local project. Each circle is a commit. A huge thanks to the Learn Git Branching Applet for providing a means of simulating and visualizing Git workflows. We'll use these diagrams to grasp what we're doing.

In the image above, our local repo is synced with the remote repo–both have two commits. The boxes pointing at the commits point to the where (or, more accurately, when) in the project a branch is. Here, the master branch is at the latest commit, C2. The head is denoted by the asterisk (*) indicates where in a project's history we are working. Most often, the head points to the latest checkpoint, like a tape recorder head might rest on the freshest spot of tape, or a record player needle might point to the most recent song.

Saving Progress

In plain English, let's talk about the meat and and potatoes of a Git workflow: staging, committing, and pushing. These actions are essential to saving changes to your work. You should do them every time you make a substantial change.

To stage, we execute git add in our project's directory. Innocuous enough! git add . and git add FILE.js will stage all files in the directory or only the FILE.js file, respectively. By stage, we mean tell Git we want to track the changes made to these files.

To commit, we execute git commit -m "COMMIT MESSAGE to record the changes made to staged files in our project's git history. Committing is roughly the same thing as saving, though the only thing we're saving is the changes to the files, not the files themselves. See How to Write Useful Commit Messages for advice on how to do just that. The following illustration shows the state of our project after the previous two commands. Our local project repo is ahead of the remote by one commit!

To push, we execute git push. By default, this command will upload our code in its current branch to a server (known as the remote in Git parlance and named origin by default). We can specify which branch to push by passing it in as an option like so : git push REMOTE_NAME BRANCH_NAME.

Now our local and remote repos are in sync! With add, commit, and push at our disposal, we're equipped to track changes to our project. Lugging this verbiage around begs the question, "When will we ever need this?" Commit every substantial change to your work. Commit! Set up your sessions controller? Implementing authorization and just amended your user model? Commit! Fix a bug? Commit!

Stage and commit every little milestone of your work. When you finish a work session, or as needed, push these changes so they're accessible to others. In short (and for example):

git add .
git commit -m "Refactor custom Account model methods"
git push

Damage Control with Branches

Many are tempted to work exclusively in the master branch. This behavior would be akin to me writing this blog post in pen longhand, while sitting at a rolling desk on a rocking boat yelling, "I make no mistakes!" Consider the master branch to be your final draft branch, the public face of your project. As we work on our projects, the master branch will be where our changes come home to rest, but those changes will first be conceived and nurtured in their own branches before being merged.

A branch of a Git project is a parallel universe. When we create a branch, we are able to make changes to our project as it existed in the moment we branched while protecting the master branch from new, more volatile code.

Before you go about turning your dreams into reality, consider giving spirit form by identifying the distinct building blocks of your project. A web application, for example, often adheres to a Model-View-Controller architecture, with separate models, controllers, and views for different aspects of the application. As we work on our project with Git, it behooves us to create new branches for each model, controller, and view as they're implemented. Further on down the road, we may create branches for new features or bug fixes.

Branching in Git is as simple as git branch BRANCH_NAME. This command creates a new branch. To work in that branch, we need to check it out, like we would a book at the library. git checkout BRANCH_NAME does the trick. Since we're lucky enough to be working in a field where laziness is a virtue, we can abridge this process. git checkout -b BRANCH_NAME will both create and checkout a branch.

Once we've created a branch, we can save our progress with add and commit as usual. Remember that executing git push will upload our project as it exists in the last commit in the current branch. The diagram below shows the state of our project after doing all of the above. Note the location of the asterisk! It is on account-m on account of us being in that particular branch.

The image above shows the master branch pointing to an earlier commit than the account-m branch. Since we've committed in account-m, master is behind! When the purpose of a feature branch has been fulfilled and its quality is satisfactory, it's time to merge that branch back into the master branch. Intuitively enough, we accomplish this feat with git merge.

First, we checkout the master branch, then we execute git merge BRANCH_NAME.

Notice the location of the asterisk! We're now in the master branch. Now merge the account-model branch and push our changes to remote.

In short, we've accomplished the following...:

$ git checkout -b account-model
A half-hour of thought and toil passes...
$ git add .
$ git commit -m "Create basic Account migration and model"
$ git checkout master
$ git merge account-model

Putting It All Together

We now know how to save our progress and to create progress in a safe place before making it a lasting part of our project. Now let's look at how this workflow plays with others.

Say we're working with someone else on this project. They are going to, say, flesh out the controller for the accounts model we created previously. They go off, clone (aka download) our repository, work, faithfully commit, and push their changes to remote. If we want to see their work on our machine, we need to pull what is on the remote, with git pull.

Notice that the asterisk is on the master branch, two commits behind our colleague's branch. Our colleague isn't quite done yet, so we decide to work on a separate feature on a separate branch. We do so, and make a couple commits' worth of progress.

In the meantime, our colleague finished and pushed their last commit for their branch. We promptly pull it to stay abreast.

We finish with our work, and decide it's time to put everything together, merging and (of course!) pushing the result to the remote so our team can work from it.

This process is the basic unit of a Git branching workflow. Each member of a team project works on a branch appropriate to a particular feature, component, or variation of the project. Commits are made and pushed with every milestone. When a particular branch has served its purpose and is ready for the big time, it is merged into the master branch. And on and on it goes!

Resolving Conflicts

Invariably, you will run into conflicts. Resolving them is beyond the scope of this blog post, but here are a tip for avoiding them and resources for dealing with them.

To avoid merge conflicts, each branch has contain changes that only pertain to separate files. If the branches being merged both have variations of the same file, it'll be time to resolve conflict.

Resolving merge conflicts is far from terrible! Visual Studio Code, Github (if you're making pull requests on the repo instead of locally merging), and even your native terminal provide tools for editing and resolving differences between conflicting files.

Now What?

Many of us, when we first start learning Git, do so just out of the demands of interfacing with others through our job or the Internet. Maybe we want to host our projects on Github and share our work with the world! Maybe we can only take a crack at someone else's work by accessing it through Bitbucket.

Strictly speaking, you don't have to be plugged in to the Web to use Git. Whether we're working alone, in pairs, or in a small group, a couple of guidelines and handful of Git commands will enhance our ability to organize, collaborate, and more fully realize the vision of our projects. Whatever software you start or contribute to, and even if you're working alone, take care to employ Git with best practices so you reap the rewards of a well-managed project.

Resources and References

Authentication and Authorization à la Rails bcrypt

Levi — Fri, 06 Dec 2019 00:21:10 +0000

Introduction

User accounts are an indispensable feature of web applications. They allow us to create persistent, tailored experiences for the people using our site. They also help us better track how our application is used. Despite their usefulness, implementing user accounts can be akin to opening Pandora's box of troubles.

We live in an age of savvy sackers of digital domains. While we've opened a box of possibilities, they've brought a host of problems with them! How do we stand a chance? We lean on others' work and trade configuration for convention. But before we find some shoulders to stand on, let's get a sense of the problem we're trying to solve.

Signing Up And Signing In

Signing Up and Signing In are actions with which we are all familiar. They allow web applications to authenticate and authorize their users.

When we Sign Up, we create a means by which a web application determines that we are who we say we are. Signing Up happens once in the lifetime of a user in an application. It creates a new user instance in the backend of the server with information that can be use to authenticate that user. Authentication asks the question, "Are you who you say you are?" When we sign in, we are authenticated by the application based on the username and password we provide, and consequently given access to different features of the application.

We are engaged in single-factor authentication when we only have to provide one type of information to authenticate ourselves. As you might imagine, single-factor authentication is not the best means of securing user accounts, as anyone with a username and password can access an account. That's where multi-factor authentication comes into play. We encounter multi-factor authentication pretty well every day, when a site asks us to enter a randomly generated code sent to our phones in addition to our username and password, or when an ATM machine requires us to enter a PIN number and insert our debit card. We won't build multi-factor authentication in this post, but it's important to be aware of.

Once we're signed in and authenticated by an application, it will check to see if we are authorized to perform the actions we attempt to perform. Authorization asks the question, "Are you allowed to do that?" The means by which a web application authorizes a user is through cookies, specifically, session cookies.

A cookie is a bit of data stored on a user's browser. Web applications can store all kinds of information in cookies to track a user's state and history. A session cookie is a cookie that lasts for the duration of a session on a web application, typically from sign/log in to sign/log out.

When a user signs in, the user's browser is given a cookie by the web application identifying that user. The authorization of the user can then be checked when HTTP requests are made of the application.

Signing up happens once in the lifetime of user on a web application. It gives the application a means of authenticating the user, or checking to see that they are who they say they are, through a username, password, and any other required information. When a user signs in, they are authenticated and given an identifying session cookie. As the user interacts with the application, the application can check to see that the user is authorized, or permitted, to perform an action by referencing the user's cookie.

Authentication with bcrypt

Authentication is a web application's way of checking to see that a user is who they say they are. There are several Ruby gems already written to facilitate this process. devise is one of the most popular, along with omniauth and doorkeeper. We're not going to use any of those! For the purposes of understanding the process of authentication and authorization, we'll be using a gem that's been staring you in the face since you first opened a Rails Gemfile: bcrypt. Uncomment that guy!

source 'https://rubygems.org'
git_source(:github) { |repo| "https://github.com/#{repo}.git" }

# ruby '2.5.1'

...

# Use Redis adapter to run Action Cable in production
# gem 'redis', '~> 4.0'
# Use ActiveModel has_secure_password
gem 'bcrypt', '~> 3.1.7'

# Use ActiveStorage variant
# gem 'mini_magick', '~> 4.8'

...

bcrypt the Ruby gem is based on bcrypt the OpenBSD hashing algorithm. Given any string, such as a password, the hash will scramble the string along with a dash of random characters (known as salt) in such a way that the process cannot be reversed or guessed. bcrypt the Ruby gem allows us to use the bcrypt algorithm to hash passwords, and it also manages storing the salt used in hashing so that we can later authenticate our users.

pw = BCrypt::Password.create('P4ssW02d!')
# => "$2a$12$YNW0EG8VwLmy1l9yxMeyAOaen/Yhx7LTBJR6G7jnG2WMkr9fo7aO6"

pw == 'P4ssW02d!'
# => true

There is a lot that bcrypt doesn't do for us. We need to alter our user database table, model, controller, and views to make use of bcrypt's functionality.

bcrypt and the User Model

In order to use bcrypt, our user table must have a password_digest attribute. In your Rails projects, you might execute the following: rails generate resource User username password_digest. After migrating the table, we should have a schema similar to the following:

  create_table "users", force: :cascade do |t|
    t.string "username"
    t.string "password_digest"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
  end

Note that we're storing a password digest, not a password. Never, ever, for any reason, whatsoever, even if your mother asks you too, even if you think it will cure your foot fungus, never store passwords in plain text.

We must also add has_secure_password to our User model. You'll notice that I've added some validations to ensure our users are created with a unique username and non-unique password. Do not require unique passwords, as it will give ne'er-do-wells the information and confidence they need to gain access to user accounts.

class User < ApplicationRecord
  has_secure_password
  validates :username, presence: true, uniqueness: true
  validates :password, presence: true
end

has_secure_password is a helper method for models that gives them access to methods which will aid in authentication. We can test them in rails console.

usr = User.create(username: "cheetochester", password: "Ch33zy$", password_confirmation: "Ch33zy$")
# => #<User id: 4, username: "cheetochester", password_digest: "$2a$12$Io.kXzHPXoGZYzuWBawSFOawjvGNmsrHsCiXbNhlYep..." ...>

usr.authenticate("cheesys")
# => false

usr.authenticate("Ch33zy$")
# => #<User id: 4, username: "cheetochester", password_digest: "$2a$12$Io.kXzHPXoGZYzuWBawSFOawjvGNmsrHsCiXbNhlYep..." ...>

Note that when we create a new user, we do so with the password and password_confirmation keys, not password_digest. bcrypt handles validating password and password_confirmation and converting password into the password_digest that is saved in the database. Given a password string, the #authenticate method returns false if the password is incorrect, and the user instance if the password is correct.

Routes

Before we can confidently set up our controllers, we must have a clear vision of our routes. In this basic example application, users can create and view their accounts. They can also sign in and out of their accounts. We will manage this functionality with the following routes in rails-app/config/routes.rb:

Rails.application.routes.draw do
  resources :users, only: [:create, :show]
  get "/signup", to: "users#new"
  get "/login", to: "sessions#new"
  post "/sessions", to: "sessions#create"
  delete "/sessions", to: "sessions#destroy"
  # For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
end

Creating a Sign Up Form

The code excerpt below depicts a basic User controller. We have supported actions for creating a user and seeing their page.

class UsersController < ApplicationController
  def new
    @user = User.new
  end

  def create
    @user = User.create(user_params)
    if @user.valid?
      @user.save
      redirect_to @user
    else  
      redirect :new
    end
  end

  def show
    @user = User.find(params[:id])
  end

  private

  def user_params
    params.require(:user).permit(:username, :password, :password_confirmation)
  end
end

There is no special sauce for creating a sign up form. We simply need a form that will pass username, password, and password_confirmation to our application. In rails-app/app/views/users/new.html.erb we can generate a form with Rails form helpers like so:

<%= form_for @user do |f| %>
  <%= f.label :username %>
  <%= f.text_field :username, placeholder: "Username" %>
  <%= f.label :password %>
  <%= f.password_field :password, placeholder: "Password" %>
  <%= f.label :password_confirmation %>
  <%= f.password_field :password_confirmation, placeholder: "Confirm Password" %>
  <%= f.submit "Create Account" %>
<% end %>

On submission, our UsersController#create action will attempt to create a new user instance with those parameters. If the user instance is valid, the user will be redirected to their show page. Otherwise, the user will be redirected to the new user page.

Now that we have handled signing up a user, let's tackle signing them in.

Logging In

Logging in, or signing in, will be handled through Rails' session hash, which reads and manages a session cookie on a user's browser. Managing session requires enough unique actions to warrant another controller. We'll call this controller the SessionsController.

class SessionsController < ApplicationController
  def new
  end

  def create
    @user = User.find_by(username: params[:username])
    if @user && @user.authenticate(params[:password])
      session[:user_id] = @user.id
      redirect_to @user
    else  
      redirect_to login_path
    end
  end
end

In this controller we've defined two actions. SessionsController#new is simply responsible for rendering a page that enables a user to create a new session (also known as log in). The contents of rails-app/app/views/sessions/new.html.erb maybe as simple as:

<%= form_tag sessions_path do %>
    <%= label_tag "Username" %>
    <%= text_field_tag :username, nil, placeholder: "Username" %>
    <%= label_tag "Password" %>
    <%= password_field_tag :password, nil, placeholder: "Password" %>
    <%= submit_tag "Log In"%>
<% end %>

The purpose of this form is to prompt the authentication of a user and the storage of their identity in the session cookie. In SessionsController#create, we first try to find the user based on their username. If the user exists, we authenticate them using the password provided in the form and the #authenticate method granted to us by the bcrypt gem. If they are authenticated, we will store their id in the session cookie (session[:user_id] = @user.id). Otherwise, they will be redirected to the login path.

What keeps someone from simply modifying their session cookie to mimic a user? Lucky for us, Rails encrypts the cookies that it creates!

Authorization with bcrypt

Laying the Foundation for Authorization

We've implemented authentication with a couple of forms, a handful of routes and controller actions, and a few bcrypt methods. And yet a one-winged bird can't fly. We need authorization to put our authentication to work. We can lay the foundation for authorization by writing helper methods in rails-app/app/controllers/application_controller.rb.

class ApplicationController < ActionController::Base
  helper_method :logged_in?, :current_user

  def current_user
    if session[:user_id]
      @user = User.find(session[:user_id])
    end
  end

  def logged_in?
    !!current_user
  end

  def authorized
    redirect_to login_path unless logged_in?
  end
end

Here we've defined a few helper methods for use in our controllers and views. ApplicationController#current_user looks for a value in the :user_id key of the session cookie-hash. If there is one, the corresponding user instance will be returned. Otherwise, the return value is nil. #logged_in? coerces the return value of current_user into a Boolean by use of a double-bang. #authorized will trigger a redirect to the login page unless a user is logged in (that is, unless a value of session[:user_id] exists and it matches the value of an id of an existing user).

Since all of our controllers inherit from ApplicationController, we can go ahead and use these methods in them. helper_method let's us use the methods arguments passed to it in our views.

Authorization in Controllers

The before_action callback method can help us make short work of using our authorization methods. In our UsersController, we'll add:

class UsersController < ApplicationController
  before_action :authorized, only: [:show]

  ...
end

With this line, the application will check to see if a user is logged in and redirect to the login path if they aren't before the #show action is even fired. But the fun doesn't stop here. We can leverage our authorization helper methods to conditionally render our views!

Authorization in Views

In rails-app/app/views/layouts/application.html.erb, let's add a login/logout button below our view template. That way, it will appear on any pages we add to our application. Recall that <%= yield %> in application.html.erb is where the templates corresponding to our controller actions get rendered.

<!DOCTYPE html>
<html>
...

  <body>
    <%= yield %>

    <br>

    <% if logged_in? %>
      <%= button_to "Logout", sessions_path, method: :delete %>
    <% else %>
      <%= button_to "Login Page", login_path, method: :get %>
    <% end %>
  </body>
</html>

Since we defined the #logged_in? helper method and passed :logged_in? as an argument to helper_method in our ApplicationController, we are able to use it in our views. This bit of erb renders a logout button if a user is logged in, and vice versa.

We can get even more specific. Since we have a helper method current_user that returns the user of the current session, we can render custom content for that user. On the rails-app/app/views/users/show.html.erb page, we can make it so that a user sees special content if they're on their own show page.

<h1>Welcome to the page of <%= @user.username %></h2>

<% if current_user == @user %>
  <h3>This is my page!!!</h3>
<% end %>

Logging Out

Every good story has to come to an end. When a user logs out, they are essentially ending their session. One basic way of ending a user's session is to set the value of session[:user_id] to nil. We'll add the following action to our SessionsController to do so.

class SessionsController < ApplicationController
  ...

  def destroy
    session[:user_id] = nil
    redirect_to login_path
  end
end

If you're the observant type, you'll have noticed that the logout button we created last section makes the HTTP request that will be routed to this action. With that action, the session cookie will cease to know about the user and the user will not be authorized in the application.

Conclusion

And that's all it takes to build out basic authentication and authorization in a Rails application with bcrypt! When we authenticate a user, we check to see they are who they say they are. We facilitate authentication in a web application through sign up and sign/log in forms. To make use of authentication, we track user state in a session cookie and use that cookie to perform authorization before relevant actions in our application.

bcrypt helps us implement authentication by giving us a means of securely storing and cross-referencing authentication factors (like passwords) in our database. To authorize users, we write helper methods that use some of those means as well as the built-in Rails sessions cookie to check user state and react accordingly.

Now that you have some idea of how it works, try to implement it yourself! When you're comfortable using bcrypt, break out the big guns like devise and try again. Authentication and authorization are essential parts of secure web applications. We'll all be better off if you use them. And never store plain text passwords in a database.

Jumpstarting Applications with ActiveRecord

Levi — Wed, 13 Nov 2019 05:49:57 +0000

Why ActiveRecord is Awesome

ActiveRecord is a Ruby gem that serves up an object relational mapper (ORM) for relational database management systems (RDBMSs). In this post, we'll explore how to use it outside of the Rails ecosystem in the service of fleshing out a simple domain model.

ActiveRecord provides a Ruby interface for creating, reading, updating, and deleting a database and its constituent tables and data. This interface comes without requiring you to rewrite more than a configuration file when switching from SQLite to PostgreSQL. Databases are a useful addition to any Ruby application because they give us a place to save data--Ruby "flushes" data after each execution session.

A lot of people encounter ActiveRecord for the first time when crossing the tracks into Rails territory, but ActiveRecord can be leveraged without the trappings of the entire Rails framework. Any Ruby project that involves a database can benefit from the features ActiveRecord provides!

What You Need

File Directory Structure and Gems

Let's start by laying out a basic file directory structure for our application. You may have you own ideas and preferences--that's more than alright. The structure I'm about to present is a stripped-down version of what you might see in a Rails project. Go to town laying this out with mkdir and touch in your directory or start clicking away in your file browser.

app/
 » models/
    » planet.rb
config/
 » environment.rb
 » database.yml
db/
 » migrate/
 » seeds.rb 
Gemfile
Rakefile
README.md

It takes a village to raise an application! We'll start by filling in the Gemfile in our project directory and calling out the gems we want and need.

# where Bundler will look for gems if they're not already installed
source 'https://rubygems.org'

# Ruby's quintessential ORM
gem 'activerecord'
# generates fake data, mostly strings
gem 'faker'
# allows us to create and run tasks from the command line
gem 'rake'
# enables us to import a whole folder's worth of code into a file
gem 'require_all'
# gives us useful Rake tasks for managing a database
gem 'sinatra-activerecord'
# provides us with a primitive Ruby-SQLite3 database
gem 'sqlite3'

If you don't have Bundler installed, now's a good time to hop on the wagon. gem install bundler ought to do the trick in your terminal.

With Bundler installed, installing our project's gems is as easy as bundle install (or bundle, if you're feeling lazy). Bundler scans the gem file for our projects dependencies and downloads and installs whatever is not already on our system. Bundler makes it quick and easy to get any system up to speed with a Ruby application.

Ruby Environment and Database Configuration

Let's take a little trip into the config/ directory. In environment.rb we will centralize importing gems and local Ruby files so that we need only require environment.rb in our run files to get things done.

require 'bundler'
Bundler.require
require_all 'app'

That wasn't so hard, was it? require 'bundler' makes it so that we can execute the following line Bundler.require and essentially require everything in the Gemfile. require_all 'app' requires all local .rb files in the app/ folder.

Now comes the weird part. In database.yml, copy-paste the following code [source]:

# 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

Here we specify what kind of RDBMS we are interfacing with, the name and location of the database file (if it doesn't exist it will be generated), then maximum number of open connections (pools) to the database, and the time limit for query operations. sinatra-activerecord will refer to this file by default to configure the connection between ActiveRecord and the SQLite database.

Rake Tasks

Rake is a Ruby gem that allows us to run tasks, or snippets of Ruby code, from the command line. It also gives us the ability to tidily define these within a file known as the Rakefile. In our Rakefile, let's write the following:

# imports everything (gems and local files) specified in environment.rb
require_relative 'config/environment'
# gives us an arsenal of rake tasks for managing our database
require 'sinatra/activerecord/rake'

# describes the task
desc 'starts a console'
# establishes the name of the rake option: console
task :console do
  # turns on logging of SQL queries while in the task
  ActiveRecord::Base.logger = Logger.new(STDOUT)
  # starts a Ruby REPL session
  Pry.start
end

Now, by executing rake console in our terminal while in our project directory, we will be able to start a REPL session and experiment with methods to our hearts content, all with access to the contents of our project and without the fuss and muss of managing a run file.

While ActiveRecord and Rake are separately invaluable gems, their power and usefulness is compounded with the inclusion of sinatra-activerecord. Right now, while in your project directory in your terminal, run rake -T in the command line to see your available tasks. See all the ones with the db: prefix? Sinatra gave us those.

Breathing Life into the Domain Model

Making/Mapping a Class/Model

One of the advantages of using ActiveRecord is that it is an object relational mapper. It gives us the ability to map the structure of our database to the structure of our codebase. Here's a quick refresher on the Active Record pattern of ORMs (for which the ActiveRecord gem is named) with the database element on the left and equivalent codebase element on the right:

Database = Domain
Table = Model
Column = Attribute
Row = Instance

With ActiveRecord, making our model participate in this scheme is as simple as dirt (or at least inheritance).

In app/models/planet.rb, park the following lines:

class Planet < ActiveRecord::Base

end

class Planet < ActiveRecord::Base is our golden goose, as it endows our Planet class (aka our Planet model) with all of the rights and privileges and methods of ActiveRecord therein.

I've stuck a class method in there to print all instances of our Planet class with a little flavor. Yet we've no instances to speak of! Let's fix that.

Creating the Database

ActiveRecord will look specifically for a db/ folder at the top of your project directory, along with a migrate/ subdirectory. ActiveRecord builds out a database with Ruby files called migrations, which specify the action to take on the database and the schema being added or altered.

Thanks to sinatra-activerecord, we have access to a Rake task that will generate a migration file for us. Run rake db:create_migration NAME=create_planets in your terminal.

You should now have a file that looks like TIMESTAMP_create_planets.rb. Inside it, input the following:

class CreatePlanets < ActiveRecord::Migration[6.0]
  def change
    create_table :planets do |t|
      t.string :name
      t.boolean :inhabitable

      t.timestamps
    end
  end
end

Here is the table that corresponds to our model, along with specifications for the tables columns (aka the model's attributes). Note that the table name is plural while the model name was singular (see: ActiveRecord Naming Conventions).

To create this table in our database, we need only lean on another rake task sung by Sinatra: rake db:migrate. If the migration was successful, we will have a schema.rb file in the db/ directory. Check it! Don't edit it ever! It's created and updated with each migration. It's contents should reflect the contents of our migration.

We've come a long way. It's high time we paused to test the makings of our project.

Test Driving an ActiveRecord Project

Seeding the Database

It is critical we test the functionality of our model and database before further fleshing out our project. While we could always require the formal rspec gem and write formal tests, we aren't going to do that during this foray. Instead, we'll populate our database with seed data and poke at it while in our rake console.

In the seeds.rb file, we are encouraged to write ActiveRecord methods that populate our database (hence the name "seeds"). We will do just that:

boolean_array = [true, false]
5.times do
    Planet.create(
        name: Faker::Movies::StarWars.planet, 
        inhabitable: boolean_array.sample
    )
end

These 7 lines generate 5 planets with random names and inhabitability booleans. To seed our database with this data, we simply run rake db:seed in our terminal while in the project directory. We know our seeding was successful if we get no immediate feedback.

Poking at the Database

With our database seeded, let's see if we can do some damage. Pop into the rake console by executing rake console in your terminal. This command should start a Pry session.

Let's flex some ActiveRecord methods. Our Planet model inherited from ActiveRecord::Base, so it should have gotten something for it's trouble! Here are a few things you can try:

Planet.create(name: STRING, inhabitable: BOOLEAN) creates a new instance of the Planet class with the specified parameters and saves it in the database
Planet.all returns all instances of Planet
Planet.find(2) returns the Planet instance with id == 2
planet.update(name: STRING) updates the instance of Planet (planet) with the given attribute-value pair
Planet.all.last.delete deletes the last instance of Planet in the database

Full CRUD, just like that! These are but a few of the methods ActiveRecord provides for you. Read the docs to get the full scoop.

Where To Go From Here

Once you grasp domain modeling, CRUD, and the Active Record pattern, ActiveRecord is as powerful as it is intuitive. We've said nothing about relationships between models or validating model attributes.

ActiveRecord empowers us to create and manage RDBMS in sweet, sweet Ruby. We don't need to fret about what flavor of SQL we're using or translating a sorted polymorphic has-many select into a specific query. We can focus on adhering to a rock-solid object-oriented programming pattern to build a readable and maintainable application.

That isn't to say we should simply skip over SQL (in fact, if you don't know SQL, take an hour or two the next chance you get and work through SQLBolt). A basic understanding SQL and RDBMS will help you understand what's going on under the hood of ActiveRecord so you can fix things when they inevitably break down.

When you build out your next (or current) project, think of it in terms of the data flowing through it and how that data can be encapsulated and described. Draw out a domain model and think of the models that make it up and the relationships between them. Think about the attributes that describe those models. Then make your models, write your migrations, seed your database, and play!