Ruby on Rails 🚇

All Ruby conventions apply to Ruby on Rails but working with a framework adds another superset of conventions to follow.

PORO stands for Plain Old Ruby Objects and is used to differentiate between objects inheriting functionality from Ruby-on-Rails and those that do not (the latter are POROs).

Naming

Suffix each project name with -web or -api depending on the project type.
rails new project-name rails new project-name --api
rails new project-name-web rails new project-name-api --api
Use the team template for all Ruby on Rails projects.

Use kebab-case for naming assets files.

app/assets/images/user_avatar.svg
app/assets/stylesheets/components/_card_pricing.scss
public/assets/images/error_404.svg

app/assets/images/user-avatar.svg
app/assets/stylesheets/components/_card-pricing.scss
public/assets/images/error-404.svg

When adding “non-conventional” directories in /app, use the parent directory singular name as a suffix for filenames inside that directory.

├── forms
│   └── create_otp_form.rb
├── ...
├── queries
│   └── package_query.rb
├── ...
└── services
│   └── create_user_service.rb
├── ...

Use the kebab-case project name as a namespace and prefix to name modules and engines.

engines/campaign/
lib/errors/

engines/project-name_campaign/
lib/project-name/errors/

Syntax

Use Time.current instead of Time.now or Time.zone.now to use the timezone configured in the Rails environment.

Application Architecture

Standard Rails way vs. Non-standard way

To implement a new feature, developers must decide when to leverage the standard Rails way and when to use non-standard ways instead:

The Rails way means using Rails’ built-in DSL and implicit conventions.
The non-standard Rails way means using small Plain Old Ruby Objects (POROs), resulting in custom and more explicit implementations, e.g., Non-ActiveRecord Models, form objects.

For example, a form with a nested object can be done using the Rails way with the accepts_nested_attributes_for class method in the model. It can also be done using a non-standard Rails way with a form object.

The architecture arbitration between the Rails way and the non-standard Rails way must be performed for each feature.

Tools and Frameworks

Each project has different needs and might come with some existing legacy. In the absence of an explicit reason to use different tools, developers must follow the same stack as recommended in the Nimble Rails Template.

This includes – but is not limited to – the following tools:

Frontend
- View Template with Slim
- Hotwired Turbo & Stimulus
- Stylesheets with SCSS
Backend
- Authentication with Devise
- Authorization with Pundit
- PostgreSQL database
- Redis in-memory database
- Manage background jobs with Sidekiq
- Handle pagination with Pagy
- Handle soft delete with Discard

Configuration

Use fetch to access environment variables.

config.action_mailer.default_url_options = {
  host: ENV['DEFAULT_HOST'],
  port: ENV['DEFAULT_PORT']
}

config.action_mailer.default_url_options = {
  host: ENV.fetch('DEFAULT_HOST'),
  port: ENV.fetch('DEFAULT_PORT')
}

Provide a default value for non-sensitive variables when possible (i.e. not secret credentials).
```
ENV.fetch('NON_EXISTING_NON-SENSITIVE_VARIABLE', 'default value')
```

Prefer using an initializer to store environment variables as constants. Name this file as project-name.rb:

# in config/initializers/project-name.rb
BASIC_AUTHENTICATION_USERNAME = ENV.fetch('BASIC_AUTHENTICATION_USERNAME')
BASIC_AUTHENTICATION_PASSWORD = ENV.fetch('BASIC_AUTHENTICATION_PASSWORD')

# in app/controllers/application_controller.rb
class ApplicationController < ActionController::API
  http_basic_authenticate_with name: BASIC_AUTHENTICATION_USERNAME,
                              password: BASIC_AUTHENTICATION_PASSWORD
end

Since this file is loaded on the application boot, it will fail if an environment variable is missing i.e. fast-fail strategy.

Models

Code in models must follow the same structure as Ruby classes with additional blocks.

class SomeModel < ApplicationRecord
  # extend and include custom modules
  extend SomeModule
  include SomeModule

  # refinements
  using ArrayExtensions

  # third party macros
  acts_as_paranoid

  # constants
  SOME_CONSTANT = '20'.freeze

  # attributes, enums and accessors
  attr_accessor :name, :last_name

  enum status: { inactive: 0, active: 1, blacklisted: 2 }, _suffix: true

  store_accessor :social_accounts, %i[facebook linkedin twitter]

  # relationships
  has_many :posts, inverse_of: :some_model
  belongs_to :organization, inverse_of: :some_model

  # delegations
  delegate :full_name, to: :model_decorator

  # validations
  validates :name, presence: true
  validates_with CustomValidatorClass
  validate :custom_validator_method

  # scopes
  default_scope { order(first_name: :asc) }
  scope :with_relationship, -> { include(:relationship) }

  # callbacks
  after_create_commit :notify_reviewer

  # public class methods
  class << self
    def some_method
    end
  end

  # initialization
  def initialize
  end

  # public instance methods
  def some_public_method
  end

  def model_decorator
    @model_decorator ||= ModelDecorator.new(self)
  end

  # protected methods
  protected

  def some_protected_method
  end

  # private methods
  private

  def notify_reviewer
  end
end

When dealing with PORO models, then the default structure for Ruby classes applies.

Define explicitly enum keys to avoid both data and implementation inconsistencies. The latter is often caused when non-positive values are needed.

enum status: [:inactive, :active, :blacklisted]

enum status: { inactive: 0, active: 1, blacklisted: 2 }
enum status: { inactive: -1, active: 0, blacklisted: 1 }

Use inverse_of option when defining associations to prevent avoidable SQL queries and keep models in sync.

class Author < ApplicationRecord
  has_many :books
end

class Book < ApplicationRecord
  belongs_to :author
end

class Author < ApplicationRecord
  has_many :books, inverse_of: :author
end

class Book < ApplicationRecord
  belongs_to :author, inverse_of: :books
end

Use validates with options instead of convenience methods such as validates_option_name_of.
validates_presence_of :name
validates :name, presence: true
Do not add presentation logic in models, use Decorators instead.

Non-ActiveRecord Models

Not every model is backed by a database. When to use Concerns for appearance, when to encapsulate logic in plain-old Ruby objects. – @dhh

Use Single Table Inheritance (STI) to decouple models from database tables and to map better domain concerns to separate objects.

In its simplest implementation, STI requires a type column and each sub-model to inherit from the same parent class:

class Transaction < ApplicationRecord
  TRANSACTION_TYPES = %w[Deposit Withdrawal].freeze

  validates :type, inclusion: { in: TRANSACTION_TYPES }

  def self.create_deposit(attributes = {})
    transaction_type = 'Deposit'
    #...
  end

  def self.create_withdrawal(attributes = {})
    transaction_type = 'Withdrawal'
    #...
  end
end

class Transaction < ApplicationRecord
end

class Deposit < Transaction
end

class Withdrawal < Transaction
end

In more complex implementations – where a type column is not possible – STI can be implemented manually using default_scope:

class Transaction < ApplicationRecord
  enum transaction_type: { deposit: 0, withdrawal: 1 }
end

class Deposit < Transaction

  default_scope { where(transaction_type: :deposit) }

  def initialize(attributes = {})
    super(attributes) do
      transaction_type = :deposit
    end
  end
end

Use value objects to extract domain concerns.

class DateRange
  DATE_FORMAT = '%d-%B-%Y'.freeze

  attr_reader :start_date, :end_date

  def initialize(start_date, end_date)
    @start_date = start_date
    @end_date = end_date
  end

  def include_date?(date)
    date >= start_date && date <= end_date
  end

  def to_s
    "from #{start_date.strftime(DATE_FORMAT)} to #{end_date.strftime(DATE_FORMAT)}"
  end
end

Which can be used in an ActiveRecord model:

class Event < ApplicationRecord
  def date_range
    DateRange.new(start_date, end_date)
  end

  def date_range=(date_range)
    self.start_date = date_range.start_date
    self.end_date = date_range.end_date
  end
end

Place non-ActiveRecord models – such as value objects but not only – in the directory /models along with ActiveRecord-backed models.

Optimizations

Optimize relationships to avoid n+1 queries:

Eager load relationships if needed:
```
class Booking < ApplicationRecord
  belongs_to :photographer_package

  scope :with_photographer_package, -> { includes(:photographer_package) }
end
```
In most cases, it’s better to let Rails optimize the pre-fetching logic using includes but in some cases, preload or eager_load must be used directly.
Use the gem Bullet to detect n+1 queries.

Prefer using find_each with batch_size to process large amounts of records.

User.all.each do |user|
  NewsLetter.deliver(user)
end

User.find_each(batch_size: 500).each do |user|
  NewsLetter.deliver(user)
end

Prefer using exists? over present? to check if a record exists.

User.where(email: '[email protected]').present?

User.exists?(email: '[email protected]')

Prefer using pluck to get some model attributes as an array.

active_user_emails = User.where(status: 'active').map(&:email)

active_user_emails = User.where(status: 'active').pluck(:email)

Prefer using select to get the records as an Active Record relation and where the records come with only some specific attributes.
active_users = User.where(status: 'active')
active_users = User.where(status: 'active').select(:id, :name, :email)

Prefer using insert_all to create many records at once.

users = [
  { name: 'john', email: '[email protected]' },
  { name: 'ricky', email: '[email protected]' },
  { name: 'maria', email: '[email protected]' }
]

users.each do |user|
  User.create(user)
end

users = [
  { name: 'john', email: '[email protected]' },
  { name: 'ricky', email: '[email protected]' },
  { name: 'maria', email: '[email protected]' }
]

User.insert_all(users)

Prefer using the load_async method to run multiple independent queries asynchronously. It helps to reduce the total query response time.

class DashboardsController < ApplicationController
  def index
    @users = User.active
    @courses = Course.active
    @events = Event.active
  end
end

class DashboardsController < ApplicationController
  def index
    @users = User.active.load_async
    @courses = Course.active.load_async
    @events = Event.active.load_async
  end
end

This convention is only applicable for Rails 7.0 or later.

Routes

Prefer using only over except to be more explicit about what routes are available.

resources :configurations, except: [:new, :create, :destroy]

resources :configurations, only: [:index, :show, :edit, :update]

Prefer using concern to have reusable routes.

resources :articles do
  resource :comments
end

resources :photos do
  resources :comments
end

concern :commentable do
  resources :comments
end

resources :articles, concerns: :commentable
resources :photos, concerns: :commentable

Prefer using shallow nesting to avoid deep nested routes.

resources :articles do
  resources :comments, only: [:index, :new, :create]
end

resources :comments, only: [:show, :edit, :update, :destroy]

resources :articles do
  resources :comments, shallow: true
end

Prefer using constraints to validate requests at the route level.

# In the lib/constraint/ip_validation.rb
module Constraint
  class IPValidation
    def initialize
      @black_listed_ips = Blacklist.retrieve_ips
    end

    def matches?(request)
      @black_listed_ips.exclude?(request.remote_ip)
    end
  end
end

# In the routes.rb
constraints Constraint::IPValidation.new do
  get 'some_path', to: 'some_controller#action'
end

Controllers

Code in controllers must follow the same structure as Ruby classes with specific blocks.

class SomeController < ApplicationController
  # extend and include
  extend SomeConcern
  include AnotherConcern

  # constants
  SOME_CONSTANT = '20'.freeze

  # callbacks
  before_action :authenticate_user!
  before_action :set_resource, only: :index
  before_action :authorize_resource!, only: :index
  before_action :set_requested_resource, only: :show
  before_action :authorize_requested_resource!, only: :show

  # public instance methods
  def index
  end

  def show
  end

  def new
  end

  def edit
  end

  def create
  end

  def update
  end

  def destroy
  end

  # protected methods
  protected

  def current_user
    @current_user = super || NullUser.new
  end

  # private methods
  private

  def set_resource
  end

  def authorize_resource!
  end

  def set_requested_resource
  end

  def authorize_requested_resource!
  end
end

Use strong params to whitelist the list of parameters sent to the controller.
request.parameters[:user][:name]
params.require(:user).permit(:name)
When the strong params permit multiple attributes, prefer writing them in separate lines:
params.require(:user).permit(:name, :email, :phone, :address)
params.require(:user).permit( :address, :email, :name, :phone )
It serves the following purposes:
1. Enhances readability.
2. New changes inside the parameters are more visible.
Do not add business logic in controllers. Use Forms, Queries, or Services instead.

Views

Use local variables instead of instance variables to pass data to views.

class UsersController
  def show
    @user = User.find(params[:id])
    @user_presenter = UserPresenter.new(@user)

    render new
  end
end

class UsersController
  def show
    user = User.find(params[:id])
    user_presenter = UserPresenter.new(@user)

    render new, locals: {
      user: user,
      user_presenter: user_presenter
    }
  end
end

Do not add presentation logic in views, use Presenters instead.

Project Structure

The structure is consistent with the conventional and built-in structure of Ruby on Rails – which is documented in the official Rails Guide – with the addition of unconventional directories (highlighted with *):

app/
├── assets/
├── channels/
├── controllers/
├── decorators/ *
├── forms/ *
├── helpers/
├── javascript/
├── jobs/
├── mailers/
├── models/
├── policies/ *
├── presenters/ *
├── queries/ *
├── serializers/ *
├── services/ *
├── validators/ *
├── views/
bin/
config/
engines/ *
public/
storage/
vendor/

Decorators

Decorators are POROs abstracting view methods from models.

class User < ApplicationRecord
  def full_name
    "#{first_name} #{last_name}"
  end
end

class User < ApplicationRecord
  delegate :full_name, to: :user_decorator

  def user_decorator
    @user_decorator ||= UserDecorator.new(self)
  end
end

class UserDecorator
  delegate :email, to: :user

  def initialize(user)
    @user = user
  end

  def full_name
    "#{user.first_name} #{user.last_name}"
  end

  private

  attr_reader :user
end

SimpleDelegator provides the means to delegate all public method calls to the object passed into the constructor. As all public methods of the object will be delegated, use it only in situations that require a high number of delegations.

class User < ApplicationRecord
  delegate :full_name, to: :user_decorator

  def user_decorator
    @user_decorator ||= UserDecorator.new(self)
  end
end

class UserDecorator < SimpleDelegator
  def full_name
    "#{first_name} #{last_name}"
  end
end

Decorators are meant to be used solely in backend-related areas e.g. other models, asynchronous jobs, form objects, services… When in need to format data for a view, use a presenter instead.

Forms

Forms are POROs abstracting complex logic from controllers.

class CampaignEnrollingForm
  include ActiveModel::Model

  attr_accessor :user

  def initialize(user)
    @user = user
  end

  def save(params)
    ActiveRecord::Base.transaction do
      user.assign_attributes(params)
      user.charge!
      user.enroll!

      raise ActiveRecord::Rollback unless user.save
    end

    promote_errors(user.errors)
    errors.empty?
  end

  private

  def promote_errors(child_errors)
    child_errors.each do |attribute, message|
      errors.add(attribute, message)
    end
  end
end

Include ActiveModel::Model to inherit attribute assignments and validations.
Use CRUD-like operation to name public methods providing an ActiveRecord-like interface e.g. save, update or destroy.

Read a detailed overview of Form Objects on the Nimble blog 🚀

Policies

Policies are POROs handling authorization logic.

class CampaignPolicy < ApplicationPolicy
  def edit?
    user.completed_onboarding?
  end

  def update?
    user.completed_onboarding?
  end

  def manage?
    false
  end

  alias index? manage?
  alias show? manage?
  alias new? manage?
  alias create? manage?
  alias destroy? manage?
end

Prefer using the gem pundit to implement authorization logic.

Presenters

Presenters are POROs abstracting view methods from models, controllers and views.

# app/views/users/show.html.slim
span.onboarding__message
  - if user.onboarded?
    = t('users.onboarding.welcome')
  - else
    = t('users.onboarding.welcome_back')

# app/views/users/show.html.slim
span.onboarding__message
  = user_presenter.onboarding_message

# app/presenters/user_presenter.rb
class UserPresenter
  attr_reader :user

  def initialize(user)
    @user = user
  end

  def onboarding_message
    return I18n.t('users.onboarding.welcome') if user.onboarded?

    I18n.t('users.onboarding.welcome_back')
  end
end

Presenters logic is meant to be used solely in views-related areas e.g. web views, mailers, printed views. When in need to format data for backend purposes, use a decorator instead.

Queries

Queries are POROs abstracting complex database fetching, sorting and ordering logic.

class UsersQuery
  attr_reader :users, :filters

  def initialize(users = User.all, filters = {})
    @users = users
    @filters = filters
  end

  def call
    @users = date_filtered_users if filter_by_date.present?
    @users = users.includes(:location)
  end

  private

  def date_filtered_users
    users.where(created_at: filter_start_date..filter_end_date)
  end

  def filter_by_date
    filters[:start_date] || filters[:end_date]
  end

  def filter_start_date
    filters[:start_date].to_date.beginning_of_day
  rescue ArgumentError, NoMethodError
    start_of_time.beginning_of_day
  end

  def filter_end_date
    filters[:end_date].to_date.end_of_day
  rescue ArgumentError, NoMethodError
    Time.current.end_of_day
  end

  def start_of_time
    User.order(:created_at).limit(1).first.created_at
  end
end

For complex data computation, use database views and materialized views. Prefer using the gem scenic for an efficient integration with ActiveRecord::Migration.

Serializers

Serializers are POROs handling the rendering of API responses.

class CampaignSerializer
  include JSONAPI::Serializer

  attributes :name, :year

  has_many :users
  belongs_to :account
end

Prefer using the gem jsonapi-serializer to implement Ruby Objects serialization.

Services

Services are POROs handling business logic and the connections between the domain objects.

class CreateChargeService
  def initialize(amount:, token:, **options)
    @amount = amount
    @token = token
    @customer_id = options[:customer_id]
  end

  def call
    raise Nimble::Errors::PaymentGatewayError, charge.failure_message.capitalize unless charge.paid

    charge
  rescue PaymentGateway::Error => e
    raise Nimble::Errors::PaymentGatewayError, e
  end

  private

  attr_reader :amount, :token, :customer_id

  def charge
    @charge ||= PaymentGateway::Charge.create(amount: charge_amount,
                                              currency: Currency.default.iso_code.downcase,
                                              card: token,
                                              customer: customer_id)
  end
end

Validators

Validators are ActiveModel-based validator classes extending ActiveModel validations. A validator handles the validation of a single concern but can be applied to multiple attributes as well.

Prefer using ActiveModel::EachValidator for validating individual attributes.

class FutureDateValidator < ActiveModel::EachValidator
  def validate_each(record, attribute, value)
    record.errors.add(attribute, (options[:message] || :future_date)) unless in_future?(value)
  end

  private

  def in_future?(date)
    date.present? && Time.zone.parse(date.to_s).to_datetime > Time.zone.today
  end
end

This now can be combined with the validates method, and can be used to validate multiple attributes in a single line. This can be used in multiple models as well.

class Payroll
  include ActiveModel::Validations

  validates :pay_date, presence: true, future_date: true
end

In case a custom validator contains complex logic, consider moving it to a separate class inheriting from ActiveModel::Validator

class MyComplexValidator < ActiveModel::Validator
  def validate(record)
    if some_complex_logic
      record.errors.add(:base, :invalid)
    end
  end

  private

  def some_complex_logic
    # ...
  end
end

This now can be used with validates_with

class Payroll
  include ActiveModel::Validations

  validates_with MyComplexValidator
end

Engines

Engines are built-in into Ruby on Rails; even the Rails::Application inherits from Rails::Engine. The team uses engines to split large monolithic applications into sub-sets of mini-applications. The main benefits:

Separation of concerns with clear boundary definitions between domain objects. Even asset manifest files (CSS and JS) are split resulting in better performance and easier maintenance with direct dependencies.
Force developers to architect/design the domain objects instead of grouping everything into one main app folder.
Easier management of functionality “growth” over time. The addition of a new feature becomes a matter of deciding in which engine it fits or in rare cases if it requires a new engine.
Initial built-in horizontal scalability as each engine can be mounted independently. For instance, it’s possible to run 2 instances for a specific engine (e.g. checkout) but only 1 instance for another engine (e.g. admin) by selectively mounting engines on each instance.

Rails.application.routes.draw do
  mount ProjectNameAdmin::Engine, at: '/', if: ENGINE_ADMIN_ENABLED
  mount ProjectNameCheckout::Engine, at: '/', if: ENGINE_CHECKOUT_ENABLED
end

Engines are not a silver bullet and come with additional initial architecture and setup costs. So engine-based architecture should be preferred for medium to large applications. For small applications (< 3-5 models and controllers), the conventional architecture – placing all code in app/ – can be sufficient.

Use the kebab-case project name as a namespace for all engines for modularization purposes.

engines/
├── admin/
├── checkout/
├── settings/
├── website/

engines/
├── project-name_admin/
├── project-name_checkout/
├── project-name_setting/
├── project-name_website/

Make sure to configure the namespace in the engine:

module ProjectNameCheckout
  class Engine < ::Rails::Engine
    isolate_namespace ProjetNameCheckout
  end
end

Use singular to name engines.

engines/
├── project-name_campaigns/
├── project-name_profiles/
├── project-name_settings/

engines/
├── project-name_campaign/
├── project-name_profile/
├── project-name_setting/

Store shared domain objects – typically almost all models and policies – and functionality – typically stylesheets and JavaScript – into the main app directory. /app becomes the core application. Each engine has its own specific models, policies and assets.

app/
├── assets/
│   └── stylesheets/
│       └── core.scss
├── controllers/
├── helpers/
│   └── svg_helper.rb
├── javascript/
│   └── core.js
├── jobs/
├── mailers/
├── models/
│   ├── campaign.rb
│   ├── ...
│   └── user.rb
├── policies/ *
│   ├── campaign_policy.rb
│   ├── ...
│   └── user_policy.rb
bin/
config/
engines/
├── project-name_admin/
├── project-name_checkout/
├── project-name_settings/
├── project-name_website/
public/
storage/
vendor/

Define only shared gems in the root Gemfile. If a gem is used in only one engine, it must be defined in the engine’s gemspec file.

# In Gemfile
source 'https://rubygems.org'

ruby '2.5.3'

# Backend
gem 'rails', '6.0.0' # Latest stable.
gem 'puma' # Use Puma as the app server.

# Authorizations
gem 'pundit' # Minimal authorization through OO design and pure Ruby classes.


# In engines/project-name_auth/project-name_auth.gemspec
Gem::Specification.new do |s|
  # ...

  s.add_dependency 'devise'

  s.add_dependency 'omniauth'
  s.add_dependency 'omniauth-facebook'
  s.add_dependency 'omniauth-twitter'
end

Define all engines in the root Gemfile and into a group named engines.

gem 'project-name_admin', path: 'engines/project-name_admin'
gem 'project-name_checkout', path: 'engines/project-name_checkout'

group :engines do
  gem 'project-name_admin', path: 'engines/project-name_admin'
  gem 'project-name_checkout', path: 'engines/project-name_checkout'
end

This group can easily be required in application.rb:

require_relative 'boot'

require 'rails/all'

Bundler.require(:engines, *Rails.groups)

If a middleware is used in only one engine, it must be defined in the engine’s engine file with middleware.use instead of app.middleware.use

module ProjectNameAdmin
  class Engine < ::Rails::Engine
    isolate_namespace ProjetNameAdmin

    initializer 'project-name_admin.add_middleware' do |app|
      app.middleware.use CustomMiddleware
    end
  end
end

module ProjectNameAdmin
  class Engine < ::Rails::Engine
    isolate_namespace ProjetNameAdmin

    initializer 'project-name_admin.add_middleware' do
      middleware.use CustomMiddleware
    end
  end
end

Prefer placing all specs in the root /spec directory instead of inside the engine. The main rationale is that all specs are run together and share the same setup and configuration (/spec/support).

engines/
├── project-name_admin/
│   └── spec/ *
├── project-name_checkout/
│   └── spec/ *

engines/
├── project-name_admin/
├── project-name_checkout/
spec/
├── controllers/
│   └── project-name_admin/ *
│       └── *_spec.rb
│   └── project-name_checkout/ *
│       └── *_spec.rb

Delegations

The delegate module allows to easily expose contained objects’ public methods.

Use prefixes when the name of the delegated attribute is not explicit enough.

class User
  attr_reader :name

  belongs_to :company, inverse_of: :users

  # user.company_name
  delegate :name, to: :company, prefix: true
end

Use the private option when the delegation should be private.

class User
  attr_reader :name

  belongs_to :company, inverse_of: :users

  delegate :tax_code, to: :company, private: true
end

class User
  attr_reader :name

  belongs_to :company, inverse_of: :users

  private

  # This delegation is still public!
  delegate :tax_code, to: :company
end

Database

All practices on the Web - Database page apply to Rails projects. The following section brings practices and recommendations specific to Rails projects.

Load the database using the schema.rb file as it is faster and does not rely on the migration files.
db/setup: rails db:prepare # Will only load the schema if the DB does not exist
Use explicit steps to load the DB from the schema.rb file:
db/setup: rails db:create # creates the database if it does not exist rails db:schema:load # creates tables and columns within the existing database following schema.rb. This will delete existing data. rails db:migrate # runs migrations that have not run yet.
The docker configuration of Nimble’s Rails template creates the database when the container is built. As a consequence, The db:prepare task will not run the schema load, but only run the db migrations. At best it is slower, at worst it will raise some errors on Ruby on Rails < 7.1.0. For applications running on 7.1.0 and above, the issue should be fixed, see this blog article for more insights.

Avoid calling application functions within migration files.

class AddLocaleToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :locale, :string

    Locales.update_users_locale
  end
end

SQL commands or rake tasks are preferred options for data migrations based on the data complexity.

Using SQL commands is the preferred option if the migrating data are simple such as fixed value or current datetime.

class AddLocaleToUsers < ActiveRecord::Migration[7.0]
  def change
    add_column :users, :locale, :string

    reversible do |dir|
      dir.up do
        execute <<-SQL
          UPDATE Users SET locale='EN'
        SQL
      end
    end
  end
end

If the migrating data are complex, prefer creating rake tasks, and running them after the changes are deployed.

# awesome-web/lib/tasks/locale.rake
namespace :locale do
  desc 'Set users locale'
  task import: :environment do
    Locales.update_users_locale
  end
end

Documentation

Use YARD docblock to document public methods.

module PaymentGateway
  module V1
    class Account < Resources::BaseResource
      # @param [String] access_token
      # @param [Hash] args
      # @option args [Integer] :version
      # @return [Object]
      def retrieve_identification(access_token, args)
        #...
      end
    end
  end
end