Introdução a comandos de terminal no Ruby On Rails

A maioria esmagadora dos tutoriais ou artigos sobre o framework Ruby On Rails na internet faz muito uso da linha de comando em terminais para criação de aplicações, modelos, controladores e também para execução de tarefas com o rake como por exemplo a execução de migrations. Durante todo esse artigo vamos abordar os principais comandos usados para executar as tarefas citadas.

Rails New

O comando rails new é muito provavelmente o primeiro comando que os desenvolvedores tem contato ao conhecer o framework Rails. Esse comando cria toda a estrutura necessária para uma aplicação Rails, isto é todos os diretórios, arquivos de configuração e de dependências que o sistema precisa para ser executado. Veja na Listagem 1 um exemplo de criação de uma aplicação chamada app-exemplo-rails. Note que a sintaxe para o uso do comando é rails new [nome do projeto]. A Listagem 2 apresenta a saída deste comando.

Listagem 1. Execução do comando rails new.

~/RailsProjects/app-exemplo-rails$ rails new app-exemplo-rails

Listagem 2. Saída do comando rails new app-exemplo-rails .

     create  
        create  README.rdoc
        create  Rakefile
        create  config.ru
        create  .gitignore
        create  Gemfile
        create  app
        create  app/assets/javascripts/application.js
        create  app/assets/stylesheets/application.css
        create  app/controllers/application_controller.rb
        create  app/helpers/application_helper.rb
        create  app/views/layouts/application.html.erb
        create  app/assets/images/.keep
        create  app/mailers/.keep
        create  app/models/.keep
        create  app/controllers/concerns/.keep
        create  app/models/concerns/.keep
        create  bin
        create  bin/bundle
        create  bin/rails
        create  bin/rake
        create  bin/setup
        create  config
        create  config/routes.rb
        create  config/application.rb
        create  config/environment.rb
        create  config/secrets.yml
        create  config/environments
        create  config/environments/development.rb
        create  config/environments/production.rb
        create  config/environments/test.rb
        create  config/initializers
        create  config/initializers/assets.rb
        create  config/initializers/backtrace_silencers.rb
        create  config/initializers/cookies_serializer.rb
        create  config/initializers/filter_parameter_logging.rb
        create  config/initializers/inflections.rb
        create  config/initializers/mime_types.rb
        create  config/initializers/session_store.rb
        create  config/initializers/wrap_parameters.rb
        create  config/locales
        create  config/locales/en.yml
        create  config/boot.rb
        create  config/database.yml
        create  db
        create  db/seeds.rb
        create  lib
        create  lib/tasks
        create  lib/tasks/.keep
        create  lib/assets
        create  lib/assets/.keep
        create  log
        create  log/.keep
        create  public
        create  public/404.html
        create  public/422.html
        create  public/500.html
        create  public/favicon.ico
        create  public/robots.txt
        create  test/fixtures
        create  test/fixtures/.keep
        create  test/controllers
        create  test/controllers/.keep
        create  test/mailers
        create  test/mailers/.keep
        create  test/models
        create  test/models/.keep
        create  test/helpers
        create  test/helpers/.keep
        create  test/integration
        create  test/integration/.keep
        create  test/test_helper.rb
        create  tmp/cache
        create  tmp/cache/assets
        create  vendor/assets/javascripts
        create  vendor/assets/javascripts/.keep
        create  vendor/assets/stylesheets
        create  vendor/assets/stylesheets/.keep
        run  bundle install

Perceba na saída apresentada na Listagem 2 que uma grande quantidade de arquivos e diretórios foi criado. Estes são necessários para que o aplicativo Rails funcione normalmente. Vamos analisar em seguida algumas das estruturas criadas.

Arquivo README.rdoc

Um dos arquivos gerados foi o README.rdoc que pode ser usado para documentar o que é necessário fazer para configurar ou executar a aplicação, também para especificar as dependências, como criar a base de dados ou inicializar o banco com informações bem como instruções para implantação da aplicação.

Arquivo Gemfile

Outro arquivo gerado foi o Gemfile onde pode ser especificado as dependências ou as gems da aplicação, como o Rails, SQLite, JavaScript, etc. O arquivo Gemfile deve parecer com o exibido na Listagem 3.

Listagem 3. Exemplo do arquivo Gemfile

source 'https://rubygems.org'
   
  # Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
  gem 'rails', '4.2.4'
  # Use sqlite3 as the database for Active Record
  gem 'sqlite3'
  # Use SCSS for stylesheets
  gem 'sass-rails', '~> 5.0'
  # Use Uglifier as compressor for JavaScript assets
  gem 'uglifier', '>= 1.3.0'
  # Use CoffeeScript for .coffee assets and views
  gem 'coffee-rails', '~> 4.1.0'

Diretório app

Um dos diretórios também gerados pelo comando rails new foi a pasta app. Ela contém os componentes principais da aplicação, os modelos que são as classes que representam tabelas do banco de dados, os controladores que tratam as requisições e as visões ou páginas web que renderizam listas e formulários. Esses componentes ficam armazenados respectivamente nos diretórios app/models, app/controllers e app/views.

Diretório config

Os arquivos de configuração ficam na pasta config. Neste diretório os arquivos mais comumente usados são database.yml e routes.rb. O primeiro trata de configurações de acesso a banco de dados, como a localização ou URL do banco, também o usuário e a senha para autenticação na base. Esses dados estão divididos para três ambientes - desenvolvimento, testes e produção - como apresentado na Listagem 4.

Listagem 4. Código do arquivo database.yml.

development:
    database: db/development.sqlite3
   
  test:
    database: db/test.sqlite3
   
  production:
    database: db/production.sqlite3

O banco de dados padrão é o sqlite, caso seja necessário alterar para outra ferramenta é esse arquivo que guarda as configurações. Por exemplo veja na Listagem 5 um arquivo database.yml configurado para acessar o banco de dados PostgreSQL.

Listagem 5. Código do arquivo database.yml configurado para PostgreSQL.

development:
    adapter: postgresql
    database: nome_do_banco
    username: nome_do_usuario
    password: senha
    host: localhost
    
  test:
    adapter: postgresql
    database: nome_do_banco
    username: nome_do_usuario
    password: senha
    host: localhost
   
  production:
    adapter: postgresql
    database: nome_do_banco
    username: nome_do_usuario
    password: senha
    host: localhost

Já o arquivo routes.rb é responsável por fazer o mapeamento entre uma URL e um método em determinado controlador.

Diretório db

O diretório db é onde ficam as migrações para a aplicação que são responsáveis pela criação, remoção ou edição das estruturas do banco de dados. Nesse diretório também fica o arquivo seeds.rb que pode ser usado para preencher informações iniciais no banco de dados. Veja na Listagem 6 um exemplo de um arquivo seeds.rb inicializando uma tabela chamada cidades com o atributo nome.

Listagem 6. Exemplo de arquivo seed.rb inicializando tabela cidades.

Cidade.create(name: 'Nova Iorque' )
  Cidade.create(name: 'Los Angeles' )
  Cidade.create(name: 'Chicago' )
  Cidade.create(name: 'Houston' )

Diretórios lib, log, public e test

Na pasta lib ficam tarefas customizadas e os scripts padrões da ferramenta rake como os scripts de migração de tabelas e criação de banco de dados. No diretório log ficam os registros ou saídas que a aplicação loga, erros, avisos ou informações de depuração. Na pasta public ficam arquivos que são acessíveis por meio da URL, todos os outros tem acesso bloqueado, entre os arquivos dessa pasta estão paginas de erro, como página não encontrada (404.html) e erro interno do servidor (500.html). Também está disponível na estrutura da aplicação um diretório test que contém subdiretórios onde podem ser criados testes para modelos, controladores entre outros componentes.

Rails Generate

O comando rails generate pode ser usado para criar muitos componentes da aplicação. Existe uma combinação de opções que podem ser usadas com essa ferramenta para criar estruturas baseadas em parâmetros passados. Para ver essas opções existentes basta digitar o comando apresentado na Listagem 7, note que o comando deve ser executado dentro do diretório de uma aplicação Rails, neste caso o comando foi chamado a partir da pasta onde está localizada a aplicação criada na Listagem 1, chamada app-exemplo-rails. A Listagem 8 mostra a saída do comando.

Listagem 7. Comando para visualizar opções do rails generate.

~/RailsProjects/app-exemplo-rails$ rails generate --help

Listagem 8. Saída do comando rails generate --help.

Usage: rails generate GENERATOR [args] [options]
   
  General options:
    -h, [--help]          # Print generator's options and usage
    -p, [--pretend]    # Run but do not make any changes
    -f, [--force]        # Overwrite files that already exist
    -s, [--skip]        # Skip files that already exist
    -q, [--quiet]     # Suppress status output
   
  Please choose a generator below.
   
    assets
    controller
    generator
    helper
    integration_test
    jbuilder
    job
    mailer
    migration
    model
    resource
    scaffold
    scaffold_controller
    task

A primeira parte da saída mostra como o comando deve ser usado, deve-se escolher qual componente deseja-se criar em seguida passar, caso seja necessário, uma das General Options (Opções Gerais).

A opção -h ou --help foi a que usamos na Listagem 7, como visto ela imprime os possíveis usos do comando. A opção -p ou –pretend apenas “finge” criar o componente ou estrutura passada, mas não faz nenhuma modificação no projeto. Veja na Listagem 9, que tenta criar um scaffold (um CRUD) de uma classe chamada Cliente com os atributos nome, email e telefone passando a opção -p. Note que a saída, exibida na Listagem 10, diz que alguns arquivos foram criados mas na verdade nenhuma modificação é feita.

Listagem 9. Uso da opção -p ou --pretend.

~/RailsProjects/app-exemplo-rails$ rails generate scaffold Cliente nome:string email:string telefone:string --pretend

Listagem 10. Saída do comando rails generate scaffold -p.

     invoke  active_record
        create    db/migrate/20151230003752_create_clientes.rb
        create    app/models/cliente.rb
        invoke    test_unit
        create      test/models/cliente_test.rb
        create      test/fixtures/clientes.yml
        invoke  resource_route
        route    resources :clientes
        invoke  scaffold_controller
        create    app/controllers/clientes_controller.rb
        invoke    erb
        create      app/views/clientes
        create      app/views/clientes/index.html.erb
        create      app/views/clientes/edit.html.erb
        create      app/views/clientes/show.html.erb
        create      app/views/clientes/new.html.erb
        create      app/views/clientes/_form.html.erb
        invoke    test_unit
        create      test/controllers/clientes_controller_test.rb
        invoke    helper
        create      app/helpers/clientes_helper.rb
        invoke      test_unit
        invoke    jbuilder
        create      app/views/clientes
        create      app/views/clientes/index.json.jbuilder
        create      app/views/clientes/show.json.jbuilder

Apesar da saída apresentada parecer ter criado muitos arquivos, eles não foram criados justamente por que o gerador foi executado com a opção --pretend (fingir). Essa opção serve apenas para demostrar o dar uma ideia da quantidade de arquivos gerados pelo comando e das suas respectivas localizações.

As opções -f (force) e -s (skip) podem ser usadas quando estão sendo gerados recursos com nomes idênticos. Usando -f arquivos com nomes iguais serão substituídos pelos novos, enquanto que -s vai preservar ou pular os arquivos já existentes. Por último a opção -q omite a saída do comando, ou seja, não imprime no terminal os arquivos que foram contrídos.

Com relação aos componentes que podem ser gerados, os mais comuns são: model, controller e migration, apresentados nos tópicos seguintes.

Generate Model

A opção model permite criar um modelo, ou uma classe que representará uma tabela do banco de dados da aplicação. Para fazer isso basta passar como parâmetros para o gerador o nome da classe seguido dos seus atributos com seus respectivos tipos. Veja na Listagem 11 o uso dessa opção para criar uma classe modelo chamada Usuário contendo como atributos nome, login, email e senha, repare que este comando também deve ser executado a partir do diretório da aplicação. A Listagem 12 apresenta a saída desse comando.

Listagem 11. Uso do gerador de modelos rails generate model.

~/RailsProjects/app-exemplo-rails$ rails generate model Usuario nome:string email:string login:string senha:string

Listagem 12. Saída do comando rails generate model.

invoke active_record

create db/migrate/20151230005914_create_usuarios.rb

create app/models/usuario.rb

invoke test_unit

create test/models/usuario_test.rb

create test/fixtures/usuarios.yml

Destes aquivos criados os mais importantes agora são app/models/usuario.rb e db/migrate/20151230005914_create_usuarios.rb. O primeiro contém a definição da classe como exibido na Listagem 13.

Listagem 13. Código da classe Usuário criada a partir de um gerador.

class Usuario < ActiveRecord::Base

end

Note que a classe não faz menção de nenhum dos atributos passados como parâmetro para o gerador. Isso por que os atributos com seus tipos ficam definidos no arquivo de migração como pode ser visto na Listagem 14.

Listagem 14. Arquivo de migração para a classe Usuário.

class CreateUsuarios < ActiveRecord::Migration

def change

create_table :usuarios do |t|

t.string :nome

t.string :email

t.string :login

t.string :senha

t.timestamps null: false

end

end

end

Generate Controller

Essa opção cria um classe que estende de ApplicationController, que se torna capaz de atender a requisições do usuário. Veja na Listagem 15 como seria o comando para gerar um controlador chamado UsuarioController, com métodos index, create, edit e show. Cada método de um controlador deve estar associado a uma página html com o mesmo nome por isso perceba que a saída, exibida na Listagem 16, também gera páginas com os mesmos nomes dos métodos e elas ficam localizadas no diretório app/views.

Listagem 15. Uso do gerador de controladores rails generate controller.

~/RailsProjects/app-exemplo-rails$ rails generate controller UsuariosController index create edit show

Listagem 16. Saída do comando rails generate controller.

create app/controllers/usuarios_controller_controller.rb

route get 'usuarios_controller/show'

route get 'usuarios_controller/edit'

route get 'usuarios_controller/create'

route get 'usuarios_controller/index'

invoke erb

create app/views/usuarios_controller

create app/views/usuarios_controller/index.html.erb

create app/views/usuarios_controller/create.html.erb

create app/views/usuarios_controller/edit.html.erb

create app/views/usuarios_controller/show.html.erb

invoke test_unit

create test/controllers/usuarios_controller_controller_test.rb

invoke helper

create app/helpers/usuarios_controller_helper.rb

invoke test_unit

invoke assets

invoke coffee

create app/assets/javascripts/usuarios_controller.coffee

invoke scss

create app/assets/stylesheets/usuarios_controller.scss

A classe UsuariosController gerada deve ser parecida com o código mostrado na Listagem 17.

Listagem 17. Código gerado para a classe UsuariosController.

class UsuariosControllerController < ApplicationController

def index

end

def create

end

def edit

end

def show

end

end

Generate Migration

Essa instrução é usada para criar migrações, ou seja, arquivos responsáveis pelas criações de tabelas e evoluções das mesmas. Imagine que fosse necessário criar uma tabela no banco para armazenagem dos dados de clientes, com as colunas nome, e-mail, endereço e data de nascimento. Um simples comando gerador resolveria isso, como o apresentado na Listagem 18, note a saída do comando na Listagem 19.

Listagem 18. Uso do gerador de migrações rails generate migration, para criar uma tabela.

~/RailsProjects/app-exemplo-rails$ rails generate migration CreateClientes nome:string email:string endereco:text data_de_nascimento:date

Listagem 19. Saída do comando rails generate migration.

invoke active_record

create db/migrate/20151230013059_create_clientes.rb

O arquivo de migração criado deve ser parecido com o exibido na Listagem 20. Note que o arquivo nada mais é do que uma classe que estende suas funcionalidades de ActiveRecord::Migration. Ela possui um método change que usa a instrução create_table passando os respectivos tipos e nomes para cada coluna da tabela.

Listagem 20. Arquivo de migração gerado para a criação da tabela de Clientes.

class CreateClientes < ActiveRecord::Migration

def change

create_table :clientes do |t|

t.string :nome

t.string :email

t.text :endereco

t.date :data_de_nascimento

end

end

end

Também é possível usar a opção migration para adicionar, remover ou atualizar colunas de determinada tabela. Por exemplo, imagine que fosse necessário adicionar uma coluna telefone à tabela de clientes criada pelo arquivo de migração mostrado na Listagem 20, isso poderia ser feito executando o comando mostrado na Listagem 21.

Listagem 21. Uso do gerador de migrações rails generate migration, para adicionar colunas a uma tabela.

~/RailsProjects/app-exemplo-rails$ rails generate migration AddTelefoneToClientes telefone:string

O arquivo gerado está apresentado na Listagem 22. No caso dele a instrução add_column foi usada para adicionar a coluna telefone do tipo string a tabela clientes.

Listagem 22. Arquivo de migração gerado para adição de coluna na tabela Clientes.

class AddTelefoneToClientes < ActiveRecord::Migration

def change

add_column :clientes, :telefone, :string

end

end

Rake Tasks

O rake é um utilitário para execução de tarefas comuns como por exemplo, criação da base de dados, execução das migrações, execução de testes, exibição de informações sobre o projeto entre outras. Para saber quais tarefas estão disponíveis a serem executadas para uma aplicação basta digitar no terminal o comando exibido na Listagem 23. Esse comando mostra uma lista muito grande de scripts que podem ser executadas e uma descrição da funcionalidade de cada um deles, na Listagem 24 são mostradas as principais linhas do resultado.

Listagem 23. Comando para exibir rake tasks disponíveis.

~/RailsProjects/app-exemplo-rails$ rake -T

Listagem 24. Saída do comando rake -T.

rake about # List versions of all Rails frameworks and the environment

...

rake db:create # Creates the database from config/database.yml for the current RAILS_ENV

rake db:drop # Drops the database from config/database.yml for the current RAILS_ENV

rake db:migrate # Migrate the database

rake db:migrate:status # Display status of migrations

rake db:rollback # Rolls the schema back to the previous version (specify steps w/ STEP=n)

…

rake db:schema:dump # Create a db/schema.rb file

rake db:schema:load # Load a schema.rb file into the database

rake db:seed # Load the seed data from db/seeds.rb

…

rake db:version # Retrieves the current schema version number

…

rake routes # Print out all defined routes in match order, with names

rake stats # Report code statistics (KLOCs, etc) from the application or engine

rake test # Runs all tests in test folder

...

Abaixo analisamos alguns dos principais comandos apresentados na lista exibida na Listagem 24.

Rake db:create

Essa instrução cria o banco de dados para a aplicação, caso não exista nenhum. Geralmente a execução dessa tarefa não gera nenhum resultado no console, a menos que algum erro ocorra. A Listagem 25 mostra a execução dessa instrução.

Listagem 25. Execução da tarefa de criação do banco de dados.

~/RailsProjects/app-exemplo-rails$ rake db:create

Rake db:migrate

Para que os arquivos de migração façam efetivamente as mudanças no banco de dados, esses arquivos precisam ser executados, e esse é exatamente o objetivo do comando rake db:migrate. Veja na Listagem 26, a execução desse comando e note na saída que as migrações criadas na Listagem 20 e Listagem 22 são executadas.

Listagem 26. Execução do comando rake db:migrate.

~/RailsProjects/app-exemplo-rails$ rake db:migrate

== 20151230013059 CreateClientes: migrating ===================================

-- create_table(:clientes)

-> 0.0018s

== 20151230013059 CreateClientes: migrated (0.0019s) ==========================

== 20151230014011 AddTelefoneToClientes: migrating ============================

-- add_column(:clientes, :telefone, :string)

-> 0.0007s

== 20151230014011 AddTelefoneToClientes: migrated (0.0009s)

=======================================

Rake routes

Essa instrução lista todas as rotas disponíveis para a aplicação. Rotas são mapeamentos que o Rails faz de uma URL para um método de um controlador. Isso que dizer que uma rota faz com que um endereço eletrônico aponte pra determinado método, por exemplo ao acessar http://www.minhaaplicacao.com.br/home/index, um usuário estaria na verdade acessando a função index de um controlador chamado home. Veja na Listagem 27 a execução do comando rake routes, o resultado desse comando deve ser parecido com a tabela logo abaixo.

Listagem 27. Execução do comando rake routes.

~/RailsProjects/app-exemplo-rails$ rake routes

Rake stats

Essa instrução exibe uma tabela contendo informações ou métricas sobre a aplicação na qual é executado, trazendo informações como quantidade de controladores, modelos, classes de testes, quantidade de linhas da aplicação, entre outras estatísticas.

Rake about

Esse comando traz informações sobre versões dos artefatos ou ferramentas que estão sendo utilizados no projeto, bem como qual adaptador ou conector de banco de dados está sendo utilizado e também exibe a versão atual da base de dados da aplicação. A Listagem 28 mostra a execução dessa instrução.

Listagem 28. Execução do comando rake about.

~/RailsProjects/app-exemplo-rails$ rake about

About your application's environment

Rails version 4.2.4

Ruby version 2.1.5-p273 (x86_64-linux-gnu)

RubyGems version 2.2.2

Rack version 1.6.4

JavaScript Runtime Node.js (V8)

Environment development

Database adapter sqlite3

Database schema version 20151230014011

Conclusão

Essa foi uma pequena introdução aos principais comandos que podem ser executados para uma aplicação Ruby On Rails em um terminal ou prompt de comando. Talvez exista uma curva de aprendizado maior desses comandos para desenvolvedores que usem o sistema operacional Windows e estão acostumados com a interface gráfica, mas nada que um pouco de prática não supra essa necessidade. Após memorizar a utilidade desses comandos, especialmente os geradores, percebemos o quanto eles podem agilizar o trabalho visto que eles criam toda uma estrutura necessária que pode ser facilmente personalizada. Assim usar esses comandos evitam que o desenvolvedor gaste tempo criando arquivos que não necessariamente estão ligados as regras de negócio da aplicação, diminuindo o tempo de desenvolvimento da mesma.