La Línea de Comandos de Rails

NOTA: Este tutorial asume que tienes conocimientos básicos de Rails al haber leído la Guía de Introducción a Rails.

1 Creando una Aplicación de Rails

Primero, vamos a crear una aplicación simple de Rails usando el comando rails new.

Usaremos esta aplicación para jugar y descubrir todos los comandos descritos en esta guía.

1.1 rails new

El primer argumento que pasaremos al comando rails new es el nombre de la aplicación.

$ rails new my_app
     create
     create  README.md
     create  Rakefile
     create  config.ru
     create  .gitignore
     create  Gemfile
     create  app
     ...
     create  tmp/cache
     ...
        run  bundle install

¡Rails configurará lo que parece ser una gran cantidad de cosas para un comando tan pequeño! Ahora tenemos toda la estructura de directorios de Rails con todo el código que necesitamos para ejecutar nuestra simple aplicación desde el principio.

Si deseas omitir algunos archivos de ser generados o saltar algunas bibliotecas, puedes añadir cualquiera de los siguientes argumentos a tu comando rails new:

Estos son solo algunas de las opciones que rails new acepta. Para una lista completa de opciones, escribe rails new --help.

1.2 Preconfigurar una Base de Datos Diferente

Al crear una nueva aplicación de Rails, tienes la opción de especificar qué tipo de base de datos va a usar tu aplicación. Esto te ahorrará unos minutos y, ciertamente, muchas pulsaciones de teclas.

Veamos qué hará por nosotros la opción --database=postgresql:

$ rails new petstore --database=postgresql
      create
      create  app/controllers
      create  app/helpers
...

Veamos qué puso en nuestro config/database.yml:

# PostgreSQL. Se admiten las versiones 9.3 y superiores.
#
# Instalar el controlador pg:
#   gem install pg
# En macOS con Homebrew:
#   gem install pg -- --with-pg-config=/usr/local/bin/pg_config
# En Windows:
#   gem install pg
#       Elige la compilación win32.
#       Instala PostgreSQL y pon su directorio /bin en tu ruta.
#
# Configurar Usando Gemfile
# gem "pg"
#
default: &default
  adapter: postgresql
  encoding: unicode

  # Para detalles sobre el agrupamiento de conexiones, ve la guía de configuración de Rails
  # https://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>

development:
  <<: *default
  database: petstore_development
...

Generó una configuración de base de datos correspondiente a nuestra elección de PostgreSQL.

2 Conceptos Básicos de la Línea de Comandos

Hay algunos comandos que son absolutamente críticos para tu uso diario de Rails. En el orden de cuánto probablemente los usarás están:

• bin/rails console
• bin/rails server
• bin/rails test
• bin/rails generate
• bin/rails db:migrate
• bin/rails db:create
• bin/rails routes
• bin/rails dbconsole
• rails new app_name

Puedes obtener una lista de los comandos de rails disponibles para ti, que a menudo dependerán de tu directorio actual, escribiendo rails --help. Cada comando tiene una descripción, y debería ayudarte a encontrar lo que necesitas.

$ rails --help
Usage:
  bin/rails COMMAND [options]

Debes especificar un comando. Los comandos más comunes son:

  generate     Generar nuevo código (alias corto: "g")
  console      Iniciar la consola de Rails (alias corto: "c")
  server       Iniciar el servidor de Rails (alias corto: "s")
  ...

Todos los comandos se pueden ejecutar con -h (o --help) para más información.

Además de esos comandos, están:
about                               Lista las versiones de todos los Rails ...
assets:clean[keep]                  Elimina los activos compilados antiguos
assets:clobber                      Elimina los activos compilados
assets:environment                  Carga el entorno de compilación de activos
assets:precompile                   Compila todos los activos ...
...
db:fixtures:load                    Cargar fixtures en el ...
db:migrate                          Migra la base de datos ...
db:migrate:status                   Muestra el estado de las migraciones
db:rollback                         Revierte el esquema a ...
db:schema:cache:clear               Limpia un archivo db/schema_cache.yml
db:schema:cache:dump                Crea un archivo db/schema_cache.yml
db:schema:dump                      Crea un archivo de esquema de base de datos (ya sea db/schema.rb o db/structure.sql ...
db:schema:load                      Carga un archivo de esquema de base de datos (ya sea db/schema.rb o db/structure.sql ...
db:seed                             Carga los datos de semilla ...
db:version                          Recupera la versión actual del esquema ...
...
restart                             Reinicia la aplicación tocando ...
tmp:create                          Crea directorios temporales ...

2.1 bin/rails server

El comando bin/rails server lanza un servidor web llamado Puma que viene incluido con Rails. Lo usarás cada vez que quieras acceder a tu aplicación a través de un navegador web.

Sin más trabajo, bin/rails server ejecutará nuestra nueva y brillante aplicación Rails:

$ cd my_app
$ bin/rails server
=> Booting Puma
=> Rails 7.2.0 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 6.4.0 (ruby 3.1.3-p185) ("The Eagle of Durango")
*  Min threads: 5
*  Max threads: 5
*  Environment: development
*          PID: 5295
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

Con solo tres comandos, configuramos un servidor Rails escuchando en el puerto 3000. Ve a tu navegador y abre http://localhost:3000, verás una aplicación básica de Rails en ejecución.

El servidor puede ejecutarse en un puerto diferente usando la opción -p. El entorno de desarrollo predeterminado puede cambiarse usando -e.

$ bin/rails server -e production -p 4000

La opción -b vincula Rails a la IP especificada, por defecto es localhost. Puedes ejecutar un servidor como un daemon pasando una opción -d.

2.2 bin/rails generate

El comando bin/rails generate utiliza plantillas para crear una gran cantidad de cosas. Ejecutar bin/rails generate por sí solo proporciona una lista de generadores disponibles:

$ bin/rails generate
Usage:
  bin/rails generate GENERATOR [args] [options]

...
...

Por favor elige un generador a continuación.

Rails:
  assets
  channel
  controller
  generator
  ...
  ...

NOTA: Puedes instalar más generadores a través de gemas de generadores, partes de plugins que sin duda instalarás, ¡e incluso puedes crear los tuyos propios!

Usar generadores te ahorrará una gran cantidad de tiempo escribiendo código plantilla, código que es necesario para que la aplicación funcione.

Vamos a hacer nuestro propio controlador con el generador de controladores. Pero, ¿qué comando deberíamos usar? Preguntemos al generador:

$ bin/rails generate controller
Usage:
  bin/rails generate controller NAME [action action] [options]

...
...

Descripción:
    ...

    Para crear un controlador dentro de un módulo, especifica el nombre del controlador como una ruta como 'parent_module/controller_name'.

    ...

Ejemplo:
    `bin/rails generate controller CreditCards open debit credit close`

    Controlador de tarjeta de crédito con URLs como /credit_cards/debit.
        Controlador: app/controllers/credit_cards_controller.rb
        Prueba:      test/controllers/credit_cards_controller_test.rb
        Vistas:      app/views/credit_cards/debit.html.erb [...]
        Helper:      app/helpers/credit_cards_helper.rb

El generador de controladores está esperando parámetros en la forma generate controller ControllerName action1 action2. Hagamos un controlador Greetings con una acción de hello, que nos dirá algo agradable.

$ bin/rails generate controller Greetings hello
     create  app/controllers/greetings_controller.rb
      route  get 'greetings/hello'
     invoke  erb
     create    app/views/greetings
     create    app/views/greetings/hello.html.erb
     invoke  test_unit
     create    test/controllers/greetings_controller_test.rb
     invoke  helper
     create    app/helpers/greetings_helper.rb
     invoke    test_unit

¿Qué generó todo esto? Se aseguró de que un montón de directorios estuvieran en nuestra aplicación, y creó un archivo de controlador, un archivo de vista, un archivo de prueba funcional, un helper para la vista, un archivo JavaScript y un archivo de hoja de estilos.

Revisa el controlador y modifícalo un poco (en app/controllers/greetings_controller.rb):

class GreetingsController < ApplicationController
  def hello
    @message = "Hola, ¿cómo estás hoy?"
  end
end

Luego la vista, para mostrar nuestro mensaje (en app/views/greetings/hello.html.erb):

<h1>¡Un Saludo para Ti!</h1>
<p><%= @message %></p>

Inicia tu servidor usando bin/rails server.

$ bin/rails server
=> Booting Puma...

La URL será http://localhost:3000/greetings/hello.

Rails viene con un generador para modelos de datos también.

$ bin/rails generate model
Usage:
  bin/rails generate model NAME [field[:type][:index] field[:type][:index]] [options]

...

Opciones de ActiveRecord:
      [--migration], [--no-migration]        # Indica cuándo generar la migración
                                             # Predeterminado: true

...

Descripción:
    Genera un nuevo modelo. Pasa el nombre del modelo, ya sea CamelCased o
    subrayado, y una lista opcional de pares de atributos como argumentos.

...

NOTA: Para una lista de tipos de campo disponibles para el parámetro type, consulta la documentación de la API para el método add_column para el módulo SchemaStatements. El parámetro index genera un índice correspondiente para la columna.

Pero en lugar de generar un modelo directamente (lo haremos más adelante), configuremos un scaffold. Un scaffold en Rails es un conjunto completo de modelo, migración de base de datos para ese modelo, controlador para manipularlo, vistas para ver y manipular los datos, y un conjunto de pruebas para cada uno de los anteriores.

Configuraremos un recurso simple llamado "HighScore" que hará un seguimiento de nuestra puntuación más alta en los videojuegos que jugamos.

$ bin/rails generate scaffold HighScore game:string score:integer
    invoke  active_record
    create    db/migrate/20190416145729_create_high_scores.rb
    create    app/models/high_score.rb
    invoke    test_unit
    create      test/models/high_score_test.rb
    create      test/fixtures/high_scores.yml
    invoke  resource_route
     route    resources :high_scores
    invoke  scaffold_controller
    create    app/controllers/high_scores_controller.rb
    invoke    erb
    create      app/views/high_scores
    create      app/views/high_scores/index.html.erb
    create      app/views/high_scores/edit.html.erb
    create      app/views/high_scores/show.html.erb
    create      app/views/high_scores/new.html.erb
    create      app/views/high_scores/_form.html.erb
    invoke    test_unit
    create      test/controllers/high_scores_controller_test.rb
    create      test/system/high_scores_test.rb
    invoke    helper
    create      app/helpers/high_scores_helper.rb
    invoke      test_unit
    invoke    jbuilder
    create      app/views/high_scores/index.json.jbuilder
    create      app/views/high_scores/show.json.jbuilder
    create      app/views/high_scores/_high_score.json.jbuilder

El generador crea el modelo, vistas, controlador, ruta recurso, y migración de base de datos (que crea la tabla high_scores) para HighScore. Y añade pruebas para esos.

La migración requiere que migre, es decir, ejecute algo de código Ruby (el archivo 20190416145729_create_high_scores.rb de la salida anterior) para modificar el esquema de nuestra base de datos. ¿Qué base de datos? La base de datos SQLite3 que Rails creará para ti cuando ejecutemos el comando bin/rails db:migrate. Hablaremos más sobre ese comando a continuación.

$ bin/rails db:migrate
==  CreateHighScores: migrating ===============================================
-- create_table(:high_scores)
   -> 0.0017s
==  CreateHighScores: migrated (0.0019s) ======================================

Veamos la interfaz que Rails creó para nosotros.

$ bin/rails server

Ve a tu navegador y abre http://localhost:3000/high_scores, ahora podemos crear nuevas puntuaciones altas (¡55,160 en Space Invaders!)

2.3 bin/rails console

El comando console te permite interactuar con tu aplicación de Rails desde la línea de comandos. En el fondo, bin/rails console utiliza IRB, por lo que si alguna vez lo has usado, te sentirás como en casa. Esto es útil para probar ideas rápidas con código y cambiar datos del lado del servidor sin tocar el sitio web.

Puedes especificar el entorno en el que el comando console debería operar.

$ bin/rails console -e staging

Si deseas probar algún código sin cambiar ningún dato, puedes hacerlo invocando bin/rails console --sandbox.

$ bin/rails console --sandbox
Loading development environment in sandbox (Rails 7.2.0)
Any modifications you make will be rolled back on exit
irb(main):001:0>

2.3.1 Los Objetos app y helper

Dentro de bin/rails console tienes acceso a las instancias app y helper.

Con el método app puedes acceder a los helpers de rutas nombradas, así como realizar solicitudes.

irb> app.root_path
=> "/"

irb> app.get _
Started GET "/" for 127.0.0.1 at 2014-06-19 10:41:57 -0300
...

Con el método helper es posible acceder a los helpers de Rails y de tu aplicación.

irb> helper.time_ago_in_words 30.days.ago
=> "hace aproximadamente 1 mes"

irb> helper.my_custom_helper
=> "mi helper personalizado"

2.4 bin/rails dbconsole

bin/rails dbconsole averigua qué base de datos estás usando y te lleva a la interfaz de línea de comandos que usarías con ella (¡y también averigua los parámetros de línea de comandos que darle!). Soporta MySQL (incluyendo MariaDB), PostgreSQL y SQLite3.

Si estás usando múltiples bases de datos, bin/rails dbconsole se conectará a la base de datos primaria por defecto. Puedes especificar a qué base de datos conectarte usando --database o --db:

$ bin/rails dbconsole --database=animals

2.5 bin/rails runner

runner ejecuta código Ruby en el contexto de la aplicación Rails de manera no interactiva, sin tener que abrir la consola de Rails. Por ejemplo:

$ bin/rails runner "Model.long_running_method"

Puedes especificar el entorno en el que el comando runner debería operar usando el interruptor -e.

$ bin/rails runner -e staging "Model.long_running_method"

Incluso puedes ejecutar código Ruby escrito en un archivo con runner.

$ bin/rails runner lib/code_to_be_run.rb

2.6 bin/rails destroy

Piensa en destroy como lo opuesto a generate. Descubrirá lo que hizo generate y lo deshará.

$ bin/rails generate model Oops
      invoke  active_record
      create    db/migrate/20120528062523_create_oops.rb
      create    app/models/oops.rb
      invoke    test_unit
      create      test/models/oops_test.rb
      create      test/fixtures/oops.yml

$ bin/rails destroy model Oops
      invoke  active_record
      remove    db/migrate/20120528062523_create_oops.rb
      remove    app/models/oops.rb
      invoke    test_unit
      remove      test/models/oops_test.rb
      remove      test/fixtures/oops.yml

2.7 bin/rails about

bin/rails about proporciona información sobre números de versión para Ruby, RubyGems, Rails, los subcomponentes de Rails, la carpeta de tu aplicación, el nombre del entorno actual de Rails, el adaptador de base de datos de tu aplicación y la versión del esquema. Es útil cuando necesitas pedir ayuda, verificar si un parche de seguridad podría afectarte o cuando necesitas algunas estadísticas para una instalación existente de Rails.

$ bin/rails about
Acerca del entorno de tu aplicación
Versión de Rails             7.2.0
Versión de Ruby              3.1.0 (x86_64-linux)
Versión de RubyGems          3.3.7
Versión de Rack              3.0.8
Runtime de JavaScript        Node.js (V8)
Middleware:               ActionDispatch::HostAuthorization, Rack::Sendfile, ActionDispatch::Static, ActionDispatch::Executor, ActionDispatch::ServerTiming, ActiveSupport::Cache::Strategy::LocalCache::Middleware, Rack::Runtime, Rack::MethodOverride, ActionDispatch::RequestId, ActionDispatch::RemoteIp, Sprockets::Rails::QuietAssets, Rails::Rack::Logger, ActionDispatch::ShowExceptions, WebConsole::Middleware, ActionDispatch::DebugExceptions, ActionDispatch::ActionableExceptions, ActionDispatch::Reloader, ActionDispatch::Callbacks, ActiveRecord::Migration::CheckPending, ActionDispatch::Cookies, ActionDispatch::Session::CookieStore, ActionDispatch::Flash, ActionDispatch::ContentSecurityPolicy::Middleware, ActionDispatch::PermissionsPolicy::Middleware, Rack::Head, Rack::ConditionalGet, Rack::ETag, Rack::TempfileReaper
Raíz de la aplicación          /home/foobar/my_app
Entorno               desarrollo
Adaptador de base de datos          sqlite3
Versión del esquema de base de datos   20180205173523

2.8 bin/rails assets:

Puedes precompilar los activos en app/assets usando bin/rails assets:precompile, y eliminar activos compilados más antiguos usando bin/rails assets:clean. El comando assets:clean permite despliegues rodantes que pueden seguir vinculando a un activo antiguo mientras se están construyendo los nuevos activos.

Si deseas limpiar completamente public/assets, puedes usar bin/rails assets:clobber.

2.9 bin/rails db:

Los comandos más comunes del espacio de nombres db: de rails son migrate y create, y valdrá la pena probar todos los comandos de migración de rails (up, down, redo, reset). bin/rails db:version es útil al solucionar problemas, diciéndote la versión actual de la base de datos.

Más información sobre migraciones se puede encontrar en la guía de Migraciones.

2.10 bin/rails notes

bin/rails notes busca en tu código comentarios que comiencen con una palabra clave específica. Puedes consultar bin/rails notes --help para obtener información sobre el uso.

Por defecto, buscará en los directorios app, config, db, lib y test anotaciones FIXME, OPTIMIZE y TODO en archivos con extensión .builder, .rb, .rake, .yml, .yaml, .ruby, .css, .js y .erb.

$ bin/rails notes
app/controllers/admin/users_controller.rb:
  * [ 20] [TODO] ¿alguna otra forma de hacer esto?
  * [132] [FIXME] alta prioridad para el próximo despliegue

lib/school.rb:
  * [ 13] [OPTIMIZE] refactorizar este código para hacerlo más rápido
  * [ 17] [FIXME]

2.10.1 Anotaciones

Puedes pasar anotaciones específicas usando el argumento --annotations. Por defecto, buscará FIXME, OPTIMIZE y TODO. Ten en cuenta que las anotaciones son sensibles a mayúsculas y minúsculas.

$ bin/rails notes --annotations FIXME RELEASE
app/controllers/admin/users_controller.rb:
  * [101] [RELEASE] Necesitamos ver esto antes del próximo lanzamiento
  * [132] [FIXME] alta prioridad para el próximo despliegue

lib/school.rb:
  * [ 17] [FIXME]

2.10.2 Etiquetas

Puedes añadir más etiquetas predeterminadas para buscar usando config.annotations.register_tags. Recibe una lista de etiquetas.

config.annotations.register_tags("DEPRECATEME", "TESTME")

$ bin/rails notes
app/controllers/admin/users_controller.rb:
  * [ 20] [TODO] hacer pruebas A/B en esto
  * [ 42] [TESTME] esto necesita más pruebas funcionales
  * [132] [DEPRECATEME] asegurar que este método esté obsoleto en el próximo lanzamiento

2.10.3 Directorios

Puedes añadir más directorios predeterminados para buscar usando config.annotations.register_directories. Recibe una lista de nombres de directorios.

config.annotations.register_directories("spec", "vendor")

$ bin/rails notes
app/controllers/admin/users_controller.rb:
  * [ 20] [TODO] ¿alguna otra forma de hacer esto?
  * [132] [FIXME] alta prioridad para el próximo despliegue

lib/school.rb:
  * [ 13] [OPTIMIZE] Refactorizar este código para hacerlo más rápido
  * [ 17] [FIXME]

spec/models/user_spec.rb:
  * [122] [TODO] Verificar que el usuario que tiene una suscripción funcione

vendor/tools.rb:
  * [ 56] [TODO] Deshacerse de esta dependencia

2.10.4 Extensiones

Puedes añadir más extensiones de archivo predeterminadas para buscar usando config.annotations.register_extensions. Recibe una lista de extensiones con su correspondiente expresión regular para hacer coincidir.

config.annotations.register_extensions("scss", "sass") { |annotation| /\/\/\s*(#{annotation}):?\s*(.*)$/ }

$ bin/rails notes
app/controllers/admin/users_controller.rb:
  * [ 20] [TODO] ¿alguna otra forma de hacer esto?
  * [132] [FIXME] alta prioridad para el próximo despliegue

app/assets/stylesheets/application.css.sass:
  * [ 34] [TODO] Usar pseudo elemento para esta clase

app/assets/stylesheets/application.css.scss:
  * [  1] [TODO] Dividir en múltiples componentes

lib/school.rb:
  * [ 13] [OPTIMIZE] Refactorizar este código para hacerlo más rápido
  * [ 17] [FIXME]

spec/models/user_spec.rb:
  * [122] [TODO] Verificar que el usuario que tiene una suscripción funcione

vendor/tools.rb:
  * [ 56] [TODO] Deshacerse de esta dependencia

2.11 bin/rails routes

bin/rails routes listará todas tus rutas definidas, lo cual es útil para rastrear problemas de enrutamiento en tu aplicación, o para darte una buena visión general de las URLs en una aplicación que estás tratando de familiarizarte.

2.12 bin/rails test

Rails viene con un marco de pruebas llamado minitest. Rails debe su estabilidad al uso de pruebas. Los comandos disponibles en el espacio de nombres test: ayudan a ejecutar las diferentes pruebas que esperas escribir.

2.13 bin/rails tmp:

El directorio Rails.root/tmp es, como el directorio /tmp de *nix, el lugar de almacenamiento para archivos temporales como archivos de identificación de proceso y acciones en caché.

Los comandos del espacio de nombres tmp: te ayudarán a limpiar y crear el directorio Rails.root/tmp:

• bin/rails tmp:cache:clear limpia tmp/cache.
• bin/rails tmp:sockets:clear limpia tmp/sockets.
• bin/rails tmp:screenshots:clear limpia tmp/screenshots.
• bin/rails tmp:clear limpia todos los archivos de caché, sockets y capturas de pantalla.
• bin/rails tmp:create crea directorios tmp para caché, sockets y pids.

2.14 Miscelánea

• bin/rails initializers imprime todos los inicializadores definidos en el orden en que son invocados por Rails.
• bin/rails middleware lista la pila de middleware de Rack habilitada para tu aplicación.
• bin/rails stats es excelente para mirar estadísticas sobre tu código, mostrando cosas como KLOCs (miles de líneas de código) y tu proporción de código a prueba.
• bin/rails secret te dará una clave pseudoaleatoria para usar en tu secreto de sesión.
• bin/rails time:zones:all lista todas las zonas horarias que Rails conoce.
• bin/rails boot inicia la aplicación y sale.

2.15 Tareas Rake Personalizadas

Las tareas rake personalizadas tienen una extensión .rake y se colocan en Rails.root/lib/tasks. Puedes crear estas tareas rake personalizadas con el comando bin/rails generate task.

desc "Soy una descripción corta pero completa para mi genial tarea"
task task_name: [:prerequisite_task, :another_task_we_depend_on] do
  # Toda tu magia aquí
  # Cualquier código Ruby válido está permitido
end

Para pasar argumentos a tu tarea rake personalizada:

task :task_name, [:arg_1] => [:prerequisite_1, :prerequisite_2] do |task, args|
  argument_1 = args.arg_1
end

Puedes agrupar tareas colocándolas en namespaces:

namespace :db do
  desc "Esta tarea no hace nada"
  task :nothing do
    # En serio, nada
  end
end

La invocación de las tareas se verá así:

$ bin/rails task_name
$ bin/rails "task_name[value 1]" # toda la cadena de argumentos debe ser citada
$ bin/rails "task_name[value 1,value2,value3]" # separar múltiples args con una coma
$ bin/rails db:nothing

Si necesitas interactuar con tus modelos de aplicación, realizar consultas de base de datos, etc., tu tarea debería depender de la tarea environment, que cargará tu código de aplicación.

task task_that_requires_app_code: [:environment] do
  User.create!
end

Comentarios

Se te anima a ayudar a mejorar la calidad de esta guía.

Por favor contribuye si ves algún error tipográfico o errores fácticos. Para comenzar, puedes leer nuestra sección de contribuciones a la documentación.

También puedes encontrar contenido incompleto o cosas que no están actualizadas. Por favor agrega cualquier documentación faltante para main. Asegúrate de revisar Guías Edge primero para verificar si los problemas ya están resueltos o no en la rama principal. Revisa las Guías de Ruby on Rails para estilo y convenciones.

Si por alguna razón detectas algo que corregir pero no puedes hacerlo tú mismo, por favor abre un issue.

Y por último, pero no menos importante, cualquier tipo de discusión sobre la documentación de Ruby on Rails es muy bienvenida en el Foro oficial de Ruby on Rails.