DEV Community: Daniele

Facade Pattern in Rails for Performance and Maintainability

Daniele — Thu, 02 Apr 2020 10:50:24 +0000

In today's post, we will be looking into a software design pattern called Facade. When I first adopted it, it felt a little bit awkward, but the more I used it in my Rails apps, the more I started to appreciate its usefulness. More importantly, it allowed me to test my code more thoroughly, to clean out my controllers, to reduce the logic within my views and to make me think more clearly about an application's code's overall structure.

Being a software development pattern, facade is framework agnostic but the examples I will provide here are for Ruby on Rails. However, I encourage you to read through this article and try them out regardless of the framework you are using. I'm sure that once you become familiar with this pattern, you will start seeing opportunities to use it in many parts of your codebase.

Without further ado, let's dive right in!

The Problem with the MVC Pattern

The MVC (Model-View-Controller) pattern is a software development pattern that dates back to the 1970s. It's a battle-tested solution for designing software interfaces, separating programming concerns into three main groups that communicate amongst each other in a unique way.

Many large web frameworks emerged in the early 2000s with the MVC pattern as their foundation. Spring (for Java), Django (for Python) and Ruby on Rails (for Ruby), were all forged with this trinity of interconnected elements at their core. Compared to the spaghetti-code resulting from software that did not make use of it, the MVC pattern was a huge achievement and turning point in the evolution of both software development and the internet.

In essence, the Model-View-Controller pattern allows for the following: a user performs an action on the View. The View triggers a request to a Controller which can potentially create/read/update or delete a Model. The Model transaction responds back to the Controller, which in turn renders some change that the user will see reflected in the View.

There are plenty of pros to this programming pattern. To list some:

It improves code maintainability by separating concerns
It allows for greater testability (the Models, Views and Controllers can be tested in isolation)
It encourages good coding practices by enforcing the Single Responsibility Principle of SOLID: "A class should have only one reason to change."

A phenomenal achievement for its time, developers soon realized that the MVC pattern was also somewhat limiting. Variants started to emerge, such as HMVC (hierarchical model–view–controller), MVA (model–view–adapter), MVP (model–view–presenter), MVVM (model–view–viewmodel) and others, which all sought to address the limitations of the MVC pattern.

One of the problems that the MVC pattern introduces, and the topic of today's article, is the following: who is responsible for handling complex view logic? The view should simply be concerned with presenting the data, the controller is just relaying the message it received from the model, and the model should not be concerned with any view logic.

To help with this common conundrum, all Rails applications get initialized with a helpers directory. The helper directory can contain modules with methods that assist in complex View logic.

Here is an example of a helper within a Rails application:

app/helpers/application_helper.rb

module ApplicationHelper
  def display_ad_type(advertisement)
    type = advertisement.ad_type
    case type
    when 'foo'
      content_tag(:span, class: "foo ad-#{type}") { type }
    when 'bar'
      content_tag(:p, 'bar advertisement')
    else
      content_tag(:span, class: "badge ads-badge badge-pill ad-#{type}") { type }
    end
  end
end

This example is simple but demonstrates the fact that you would want to extract this kind of decision making from the template itself in order to reduce its complexity.

Helpers are nice, but there is yet another pattern for handling complicated View logic that has become accepted through the years, and that is the Facade pattern.

Introduction to the Facade Pattern

In a Ruby on Rails application, facades are usually placed within the app/facades directory.

While similar to helpers, facades are not a group of methods within a module. A Facade is a PORO (Plain Old Ruby Object) that is instantiated within the controller, but one that handles elaborate View business logic. As such, it allows the following benefits:

Rather than having a single module for UsersHelper or ArticlesHelper or BooksHelper, each controller action can have its own Facade: Users::IndexFacade, Articles::ShowFacade, Books::EditFacade.
More so than modules, facades encourage good coding practices by allowing you to nest facades to ensure the Single Responsibility Principle is enforced. While you probably don't want facades that are nested hundreds of levels deep, having one or two layers of nesting for improved maintainability and test coverage can be a good thing.

Here is a contrived example:

module Books
  class IndexFacade
    attr_reader :books, :params, :user

    def initialize(user:, params:)
      @params = params
      @user   = user
      @books  = user.books
    end

    def filtered_books
      @filtered_books ||= begin
        scope = if query.present?
                  books.where('name ILIKE ?', "%#{query}%")
                elsif isbn.present?
                  books.where(isbn: isbn)
                else
                  books
                end

        scope.order(created_at: :desc).page(params[:page])
      end
    end

    def recommended
      # We have a nested facade here.
      # The `Recommended Books` part of the view has a
      # single responsibility so best to extract it
      # to improve its encapsulation and testability.
      @recommended ||= Books::RecommendedFacade.new(
        books: books,
        user: user
      )
    end

    private

    def query
      @query ||= params[:query]
    end

    def isbn
      @isbn ||= params[:isbn]
    end
  end
end

When Not to Use the Facade Pattern

Let's take a moment to also reflect on what facades are not.

Facades should not be placed in classes that live, for example, in the lib directory for code that needs to be displayed in the View. The facade's lifecycle should be generated in the Controller action and be used in its associated View.
Facades are not meant to be used for business logic to perform CRUD actions (there are other patterns for that, such as Services or Interactors—but that is a subject for another day.) In other words, facades should not be concerned with creating, updating or deleting. Their aim is to extract intricate presentation logic from the View or Controller and offer a single interface to access all that information.
Last but not least, Facades are not a silver bullet. They do not allow you to bypass the MVC pattern, but rather, they play along with it. If a change occurs in a Model, it will not be immediately reflected in the View. As is always the case with MVC, the controller action would have to be re-rendered in order for the Facade to display changes on the View.

Controller Benefits

One of the main, obvious benefits of Facades is that they will allow you to dramatically reduce the controller logic.

Your controller code will be reduced from something like this:

class BooksController < ApplicationController
  def index
    @books  = if params[:query].present?
                current_user.books.where('name ILIKE ?', "%#{params[:query]}%")
              elsif params[:isbn].present?
                current_user.books.where(isbn: params[:isbn])
              else
                current_user.books
              end

    @books.order(created_at: :desc).page(params[:page])
    @recommended = @books.where(some_complex_query: true)
  end
end

To this:

class BooksController < ApplicationController
  def index
    @index_facade = Books::IndexFacade.new(user: current_user, params: params)
  end
end

View Benefits

For the Views, there are two main benefits when using Facades:

Conditional checks, inline queries and other logic can be neatly extracted from the template itself making the code far more readable. For instance, you could use it in a form:

<%= f.label :location %>
<%= f.select :location, options_for_select(User::LOCATION_TYPES.map { |type| [type.underscore.humanize, type] }.sort.prepend(['All', 'all'])), multiple: (current_user.active_ips.size > 1 && current_user.settings.use_multiple_locations?) %>

Could just become:

<%= f.label :location %>
<%= f.select :location, options_for_select(@form_facade.user_locations), multiple: @form_facade.multiple_locations? %>

Variables that get called multiple times can be cached. This can offer significant performance improvements to your app and help remove pesky N+1 queries:

// Somewhere in the view, a query is performed.
<% current_user.books.where(isbn: params[:isbn]).each do |book| %>
  // Do things
<% end %>

// Somewhere else in the view, the same query is performed again.
<% current_user.books.where(isbn: params[:isbn]).each do |book| %>
  // Do things
<% end %>

would become:

// Somewhere in the view, a query is performed.
<% @index_facade.filtered_books.each do |book| %>
  // Do things
<% end %>

// Somewhere else in the view.
// Second query is not performed due to instance variable caching.
<% @index_facade.filtered_books.each do |book| %>
  // Do things
<% end %>

Testing Benefits

A major benefit of Facades is that they allow you to test singular bits of business logic without having to write an entire controller test, or worse, without having to write an integration test that goes through a flow and reaches a page just to ensure that the data presentation is as expected.

As you will be testing single POROs, this will help maintain a fast test suite.

Here is a simple example of a test written in Minitest for demonstration purposes:

require 'test_helper'

module Books
  class IndexFacadeTest < ActiveSupport::TestCase
    attr_reader :user, :params

    setup do
      @user = User.create(first_name: 'Bob', last_name: 'Dylan')
      @params = {}
    end

    test "#filtered_books returns all user's books when params are empty"
      index_facade = Books::IndexFacade.new(user: user, params: params)

      expectation = user.books.order(created_at: :desc).page(params[:page])

      # Without writing an entire controller test or
      # integration test, we can check whether using the facade with
      # empty parameters will return the correct results
      # to the user.
      assert_equal expectation, index_facade.filtered_books
    end

    test "#filtered_books returns books matching a query"
      @params = { query: 'Lord of the Rings' }
      index_facade = Books::IndexFacade.new(user: user, params: params)

      expectation = user
        .books
        .where('name ILIKE ?', "%#{params[:query]}%")
        .order(created_at: :desc)
        .page(params[:page])

      assert_equal expectation, index_facade.filtered_books
    end
  end
end

Unit testing facades considerably improves test suite performance, and every large company will eventually encounter slow test suites unless problems like these aren’t addressed with some level of seriousness.

One Facade, Two Facades, Three Facades, More?

You might encounter a scenario where a View renders a partial that outputs some data. In that case, you have the option of either using the parent facade or using a nested facade. That largely depends on how much logic is involved, whether you want to test it separately and whether it makes sense to extract the functionality.

There is no golden rule for how many facades to use or how many facades to nest within each other. That is to the developer's discretion. I generally prefer to have a single facade for the controller action and I limit nesting to a single level to make the code easier to follow.

Here are some general questions you can ask yourself during development:

Does the facade encapsulate the logic I am trying to present on the view?
Does the method within the facade make sense in this context?
Is the code easier to follow now, or harder to follow?

When in doubt, always strive to make your code as easy to follow as possible.

Conclusion

In conclusion, facades are a fantastic pattern to keep your controllers and views lean, while improving code maintainability, performance and testability.

However, like any programming paradigm, there is no silver bullet. Even the multitude of patterns that have emerged in more recent years (HMVC, MVVM, etc.) are not be-all-end-all solutions to the complications of software development.

Similar to the second law of thermodynamics, which states that the state of entropy in a closed system will always increase, so too in any software project does the complexity increase and evolve over time. In the long run, the goal is to write code that is as easy to read, test, maintain and follow as possible; facades offer exactly this.

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Guest author Daniele is a full-stack developer from Italy with an eye for clean, elegant code. He has lived and worked on three continents, and as of late, splits his time working as a digital nomad between Italy and East Asia.
Besides coding, Daniele enjoys reading, drawing and playing guitar.

Pros and Cons of Using structure.sql in Your Ruby on Rails Application

Daniele — Wed, 22 Jan 2020 14:52:31 +0000

In today's post, we'll cover the significant differences and benefits of using structure.sql versus the default schema.rb schema formats in your Ruby on Rails application. In a data-driven world, knowing how to exploit all of your database's rich features can make the difference between a successful and unsuccessful enterprise.

After evincing the main differences between the two formats, we'll outline how to switch to structure.sql and demonstrate how it can help with ensuring data integrity as well as database functionality that you might otherwise not be able to preserve.

In the post, I'll give examples of a Rails app that makes use of structure.sql with a PostgreSQL database, but the underlying concepts can be transposed to other databases as well. No real-world web application is truly complete without a reliable database to support it.

Without further ado, let's dive right in!

The Difference Between schema.rb and structure.sql

One of the first things you need to do when starting a Ruby on Rails project is to run database migrations. If you generate a User model, for instance, Rails will inevitably ask you to run migrations, which will create a schema.rb file accordingly:

rails g model User first_name:string last_name:string

Rails will generate the following migration:

class CreateUsers < ActiveRecord::Migration[6.0]
  def change
    create_table :users do |t|
      t.string :first_name
      t.string :last_name

      t.timestamps
    end
  end
end

Once the migration is executed, you will find that Rails generated a schema.rb file for you:

ActiveRecord::Schema.define(version: 2019_12_14_074018) do

  # These are extensions that must be enabled in order to support this database
  enable_extension "plpgsql"

  create_table "users", force: :cascade do |t|
    t.string "first_name"
    t.string "last_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

end

This schema.rb file is fantastic for relatively basic applications and use cases.

There are two main things to notice here:

It is a Ruby representation of your database; schema.rb is created by inspecting the database and expressing its structure using Ruby.
It is database-agnostic (i.e. whether you use SQLite, PostgreSQL, MySQL or any other database that Rails supports, the syntax and structure will remain largely the same)

However, there may come a time when this strategy becomes too limiting for your growing app.

Say, for instance, you have hundreds or thousands of migration files.

If you need to rapidly spin up a new production system, you might encounter a scenario where running them all in sequence takes too long. Or you might face a situation where some migrations contain code that was meant to be executed on an older version of your database, but that is no longer executable on the current version. You might have a situation where migrations were written with certain data assumptions that are no longer valid, which would cause the migrations to fail.

All these scenarios prevent efficiently setting up a new instance of your application⁠—be it in production or for a new team member⁠—with a simple rails db:create db:migrate command. If this were the case, how would you go about getting up to speed with a correct database schema?

Certainly, one way would be to go back and fix all the broken migrations. That's never a bad idea!

If going back and fixing a bunch of migrations is too costly, another way would be to run the rails db:setup task. This task will generate a database schema from your schema.rb file. However, what if your database contained complex logic that is not represented in the schema.rb representation of your database?

Luckily, Rails offers an alternative: structure.sql

structure.sql differs from schema.rb in the following ways:

It allows for an exact copy of the database structure. This is important when working with a team, as well as if you need to rapidly generate a new database in production from a rails db:setup task.
It allows preserving information of advanced database features. For example, if you are using PostgreSQL, it enables the use of views, materialized views, functions, constraints and so on.

Once an application reaches a certain maturity level, we have to use every trick in the book to boost efficiency, preserve data correctness, and ensure blazing-fast performance. Using structure.sql to manage the Rails database's behavior allows users to do so.

Switching From `schema.rb` to `structure.sql`

Making the change from schema.rb to structure.sql is a relatively straightforward process. All you need to do is set the following line in config/application.rb:

module YourApp
  class Application < Rails::Application
    config.load_defaults 6.0

    # Add this line:
    config.active_record.schema_format = :sql
  end
end

Then, run rails db:migrate and you should see the file in db/structure.sql. Voilà! Rails will dump the database structure using the tool specific to the database you are using (in PostgreSQL's case, that tool is pg_dump, for MySQL or MariaDB, it will contain the output of SHOW CREATE TABLE for each table, etc). It is advisable to ensure this file is under version control so that the rest of your team will have the same database structure.

A first glance at that file may be daunting: the schema.rb file was only 25 lines, whereas the structure.sql file is a whopping 109 lines! What benefits could such a large file add to the app development?

Adding Database-level Constraints

ActiveRecord is one of my favorite parts of using Rails. It allows you to query the database in a way that feels natural, almost like in a spoken language. For instance, if you want to find all a company's users named Dan, then ActiveRecord allows you to simply run a query like the following:

company = Company.find(name: 'Some Company')

# Reads just like in a natural language!
company.users.where(first_name: 'Dan')

There are some cases in which ActiveRecord falls short though. For instance, say you have the following validation on your User model:

class User < ApplicationRecord
  validate :name_cannot_start_with_d

  private

  def name_cannot_start_with_d
    if first_name.present? && first_name[0].downcase == 'd'
      errors.add(:first_name, "cannot start with the letter 'D'")
    end
  end
end

If you try to create a user with the name 'Dan', you should see an error when the validation runs:

User.create!(first_name: 'Dan')
Traceback (most recent call last):
ActiveRecord::RecordInvalid (Validation failed: First name cannot start with the letter 'D')

This is fine, but suppose you or one of your team members changed the data by bypassing ActiveRecord's validation:

u = User.create(first_name: 'Pan')

# The update_attribute method bypasses ActiveRecord validations
u.update_attribute :first_name, 'Dan'
u.first_name
=> "Dan"

As demonstrated, it is very easy to bypass the validation.

This can have disastrous consequences for our application. ActiveRecord can be a blessing as well as a curse⁠—while it has a very clean and natural DSL that makes it a pleasure to work with, it is often overly permissive when enforcing model-level validations. The solution, as you may already know, is to add database-level constraints.

rails g migration AddFirstNameConstraintToUser

This will generate a file that you can edit with the logic to disallow first names that start with the letter 'D':

class AddFirstNameConstraintToUser < ActiveRecord::Migration[6.0]
  def up
    execute "ALTER TABLE users ADD CONSTRAINT name_cannot_start_with_d CHECK (first_name !~* '^d')"
  end

  def down
    execute "ALTER TABLE users DROP CONSTRAINT IF EXISTS name_cannot_start_with_d"
  end
end

Note that it is very important to add code that successfully reverts the migration. In the above example, I have up and down directives. The up method gets executed when the migration runs, down gets executed when the migration is rolled back. Without properly reverting your database structure, you may have to do some manual house-cleaning later. I'd recommend always having a migration file that can be executed both up and down to avoid future headaches.

Now, run the migration and check whether you can bypass that constraint:

rails db:migrate

user = User.create first_name: 'Pan'
user.update_attribute :first_name, 'Dan'

ActiveRecord::StatementInvalid (PG::CheckViolation: ERROR:  new row for relation "users" violates check constraint "name_cannot_start_with_d")
DETAIL:  Failing row contains (2, Dan, null, 2019-12-14 09:40:11.809358, 2019-12-14 09:40:41.658974).

Perfect! Our constraint is working as intended. Even if, for whatever reason, we bypass ActiveRecord's validation, we can still rely on the database⁠—our ultimate goalkeeper⁠—to preserve our data integrity.

What does this have to do with structure.sql?

If you take a look at it, you'll see that the following was added:

CREATE TABLE public.users (
    id bigint NOT NULL,
    first_name character varying,
    last_name character varying,
    created_at timestamp(6) without time zone NOT NULL,
    updated_at timestamp(6) without time zone NOT NULL,
    CONSTRAINT name_cannot_start_with_d CHECK (((first_name)::text !~* '^d'::text)));

Your constraint is within the schema itself!

While schema.rb also supports database-level constraints, it is important to remember that it does not express everything your database may support such as triggers, sequences, stored procedures or check constraints. For example, this is what would happen to your schema file with the same exact migration (AddFirstNameConstraintToUser) if you were just to use schema.rb:

ActiveRecord::Schema.define(version: 2019_12_14_074018) do

  # These are extensions that must be enabled in order to support this database
  enable_extension "plpgsql"

  create_table "users", force: :cascade do |t|
    t.string "first_name"
    t.string "last_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

end

The file has not changed! The constraint was not added.

If you were to onboard a new developer to work on your project, you could potentially be operating under different database regulations.

Committing structure.sql to version control would help ensure that your team is on the same page. If you were to run rails db:setup having a structure.sql file, your database's structure will contain the above constraint. With schema.rb there is no such guarantee.

The same can be said about a production system. If you needed to rapidly spin up a new instance of your application with a fresh database⁠—and running all migrations sequentially takes a long time⁠—setting up the database from the structure.sql file would be a lot quicker. We can rest assured that the structure.sql will create our database with the exact same structure as in other instances.

Growing Pains

Managing the concise schema.rb file across a team is a far easier task than managing the verbose structure.sql file.

One of the biggest growing pains when migrating to structure.sql is ensuring that only the required changes get committed to that file, which can sometimes be difficult to do.

Say, for instance, you pull someone's branch and run the migrations specific to that branch. Your structure.sql will now contain some changes. You then go back to working on your own branch and generate a new migration. Your structure.sql file will now contain both your branch's and the other branch's changes. This can be a bit of a hassle to deal with, and there is undoubtedly a bit of a learning curve when it comes to managing these conflicts.

By using this approach, we're making a tradeoff. We have to deal with a bit of code complexity upfront that allows us to preserve our database's advanced functionality. In turn, we also have to deal with a simpler schema representation as well as not having all the power of the database at our fingertips, e.g. if we want to set a backup from a db:setup task. I posit that it's best to put up with a bit of version-control hassle than to suffer through fixing corrupt/incorrect data in a production system, or to not be able to make use of all the advanced functionality that your database offers.

Generally speaking, there are two strategies I've used to ensure my structure.sql file only contains the necessary changes to a specific branch:

Once you are done working on a branch that contains migrations, make sure you run rails db:rollback STEP=n where n is the number of migrations in that branch. This will ensure your database structure reverts to its original state.
You might forget to rollback after working on a branch. In that case, when working on a new branch, make sure you pull a pristine structure.sql file from master before creating any new migrations.

As a rule of thumb, your structure.sql file should only contain the changes relevant to your branch before being merged into master.

Conclusion

Generally speaking, when Rails applications are small or don't need some of the more advanced features that a database offers then it's safe to use schema.rb, which is very readable, concise and easy to manage.

However, as an application grows in size and complexity, an accurate reflection of the database structure is of the essence. It will allow a team to maintain the right constraints, database modules, functions and operators that otherwise wouldn't be possible. Learning to use Rails with a well-maintained structure.sql file will offer an edge that the simpler schema.rb simply cannot.

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!

Guest author Daniele is a full-stack developer from Italy with an eye for clean, elegant code. He has lived and worked on three continents, and as of late splits his time working as a digital nomad between Italy and East Asia.
Besides coding, Daniele enjoys reading, drawing and playing guitar.

DEV Community: Daniele

Facade Pattern in Rails for Performance and Maintainability

The Problem with the MVC Pattern

Introduction to the Facade Pattern

When Not to Use the Facade Pattern

Controller Benefits

View Benefits

Testing Benefits

One Facade, Two Facades, Three Facades, More?

Conclusion

Pros and Cons of Using structure.sql in Your Ruby on Rails Application

The Difference Between schema.rb and structure.sql

Switching From schema.rb to structure.sql

Adding Database-level Constraints

Growing Pains

Conclusion

Switching From `schema.rb` to `structure.sql`