Nivel inicial8 min de lectura · Publicado el

Migraciones en Ruby on Rails: crear, ejecutar y deshacer

Migraciones en Rails como commits: CreateCourses crea la tabla courses, AddDescriptionToCourses añade description y db:rollback deshace la última. Migraciones: avanza y deshazrubentejera.com CreateCoursesAddDescriptionToCoursescoursesnamedescriptionbin/rails db:migratebin/rails db:rollbacken ordendeshace la última
Cada migración es un commit de la base de datos: CreateCourses crea la tabla courses con name y AddDescriptionToCourses le añade description. db:migrate las aplica en orden y db:rollback deshace la última.

¿Qué es una migración?

Las migraciones son la forma de cambiar el esquema de tu base de datos a lo largo del tiempo de manera ordenada. Se escriben en Ruby, con un lenguaje propio (un DSL), así que no tienes que escribir SQL a mano y el mismo código sirve para distintas bases de datos.

Piensa en cada migración como un commit de Git para la base de datos: cada una es una versión nueva, se aplican en orden y se pueden deshacer. El esquema empieza vacío y cada migración añade o quita tablas, columnas o registros.

Active Record sabe qué migraciones ya se han aplicado y lleva la base de datos desde cualquier punto de su historia hasta la última versión. Después actualiza el fichero db/schema.rb para que refleje la estructura actual.

¿Cómo se crea una migración? (rails generate migration)

Si el nombre sigue un patrón concreto en CamelCase, Rails escribe el contenido por ti:

bin/rails generate migration AddDescriptionToCourses description:text
Parte Significado
Add Añadir una columna
Description Nombre de la columna
ToCourses Tabla en la que se añade
description:text Columna y su tipo

El resultado es este fichero:

class AddDescriptionToCourses < ActiveRecord::Migration[8.1]
  def change
    add_column :courses, :description, :text
  end
end

Otros patrones que entiende Rails son RemoveDescriptionFromCourses description:text (quitar una columna) y CreateCourses name:string (crear una tabla).

Así responde el generador:

      invoke  active_record
      create    db/migrate/20261111193044_add_description_to_courses.rb

La migración aparece en la carpeta db/migrate, con la fecha y la hora delante del nombre. Ese número es su versión: Rails las ordena por él.

Si el nombre no sigue ningún patrón, el fichero se crea igual, pero vacío. Por ejemplo, con DescriptionCourses:

class DescriptionCourses < ActiveRecord::Migration[8.1]
  def change
  end
end

Crear el fichero no cambia la base de datos. Para eso hay que ejecutarla.

Ejecutar la migración: rails db:migrate

bin/rails db:migrate

Rails aplica cada migración pendiente y te dice qué ha hecho:

== 20261111193043 CreateCourses: migrating ====================================
-- create_table(:courses)
   -> 0.0041s
== 20261111193043 CreateCourses: migrated (0.0041s) ===========================

== 20261111193044 AddDescriptionToCourses: migrating ==========================
-- add_column(:courses, :description, :text)
   -> 0.0025s
== 20261111193044 AddDescriptionToCourses: migrated (0.0025s) =================

Después actualiza db/schema.rb, que es la foto de la estructura actual:

ActiveRecord::Schema[8.1].define(version: 2026_11_11_193044) do
  create_table "courses", force: :cascade do |t|
    t.string "name"
    t.datetime "created_at", null: false
    t.datetime "updated_at", null: false
    t.text "description"
  end
end

Deshacer y consultar migraciones

Comando Qué hace
bin/rails db:migrate Aplica las migraciones pendientes
bin/rails db:rollback Deshace la última migración
bin/rails db:rollback STEP=3 Deshace las tres últimas
bin/rails db:migrate:redo Deshace la última y la vuelve a aplicar
bin/rails db:migrate VERSION=20261111193043 Lleva la base de datos justo hasta esa versión, hacia delante o hacia atrás
bin/rails db:migrate:status Lista cada migración y si está aplicada (up) o no (down)
bin/rails db:prepare Si la base de datos no existe, la crea, carga el esquema y los datos de db/seeds.rb; si existe, aplica lo pendiente

Así se ve un rollback de AddDescriptionToCourses: Rails sabe que lo contrario de add_column es remove_column.

bin/rails db:rollback
== 20261111193044 AddDescriptionToCourses: reverting ==========================
-- remove_column(:courses, :description, :text)
   -> 0.0163s
== 20261111193044 AddDescriptionToCourses: reverted (0.0192s) =================
bin/rails db:migrate:status
database: storage/development.sqlite3

 Status   Migration ID    Migration Name
--------------------------------------------------
   up     20261111193043  Create courses
  down    20261111193044  Add description to courses

db:prepare es el que conviene en un equipo nuevo o en un despliegue: se puede lanzar las veces que quieras y solo hace lo que falta.

Compruébalo: que la migración se pueda deshacer

Una migración que solo funciona hacia delante es una trampa para el día que tengas que volver atrás. La prueba más barata es aplicarla, deshacerla y volver a aplicarla. Eso es justo lo que hace db:migrate:redo:

bin/rails db:migrate:redo
== 20261111193044 AddDescriptionToCourses: reverting ==========================
-- remove_column(:courses, :description, :text)
   -> 0.0555s
== 20261111193044 AddDescriptionToCourses: reverted (0.0568s) =================

== 20261111193044 AddDescriptionToCourses: migrating ==========================
-- add_column(:courses, :description, :text)
   -> 0.0020s
== 20261111193044 AddDescriptionToCourses: migrated (0.0020s) =================

Si las dos mitades terminan sin error y db/schema.rb queda igual que antes, la migración es reversible. Hazlo antes de subir cada migración nueva: vale igual si la ha escrito un asistente de IA, porque redo no sabe quién la escribió, solo si funciona en los dos sentidos.

Cuando Rails no sabe deshacerla

En change, Rails deshace solo lo que sabe invertir: add_column, create_table, rename_column, add_index… No sabe invertir change_column, porque no recuerda cuál era el tipo anterior. Esta migración se aplica bien:

class ChangeNameTypeOnCourses < ActiveRecord::Migration[8.1]
  def change
    change_column :courses, :name, :text
  end
end

Pero al deshacerla, falla:

bin/rails aborted!
StandardError: An error has occurred, this and all later migrations canceled: (StandardError)



This migration uses change_column, which is not automatically reversible.
To make the migration reversible you can either:
1. Define #up and #down methods in place of the #change method.
2. Use the #reversible method to define reversible behavior.

La solución es la primera que propone el propio mensaje: escribir a mano la ida (up) y la vuelta (down).

class ChangeNameTypeOnCourses < ActiveRecord::Migration[8.1]
  def up
    change_column :courses, :name, :text
  end

  def down
    change_column :courses, :name, :string
  end
end
== 20261111200000 ChangeNameTypeOnCourses: reverting ==========================
-- change_column(:courses, :name, :string)
   -> 0.0187s
== 20261111200000 ChangeNameTypeOnCourses: reverted (0.0188s) =================

Errores frecuentes

1. Arrancar la aplicación con migraciones pendientes. Si generas una migración y no la ejecutas, la primera página que abras en desarrollo da un error 500 con este mensaje:

ActiveRecord::PendingMigrationError (

Migrations are pending. To resolve this issue, run:

        bin/rails db:migrate

You have 1 pending migration:

db/migrate/20261111193133_add_code_to_courses.rb

La solución es la que dice: bin/rails db:migrate.

2. Añadir una columna que ya existe. Si la tabla ya tiene name y generas AddNameToCourses name:string, la migración se cancela:

bin/rails aborted!
StandardError: An error has occurred, this and all later migrations canceled: (StandardError)

SQLite3::SQLException: duplicate column name: name:
ALTER TABLE "courses" ADD "name" varchar /*application='Demo'*/

Mira antes qué columnas hay en db/schema.rb. Como dice el mensaje, también se cancelan las migraciones que vinieran detrás.

3. Borrar el fichero de una migración ya aplicada. La base de datos sigue recordando esa versión, pero Rails ya no sabe cómo deshacerla. db:migrate:status la marca así:

   up     20261111193133  ********** NO FILE **********

Y el rollback se detiene:

bin/rails aborted!
ActiveRecord::UnknownMigrationVersionError:  (ActiveRecord::UnknownMigrationVersionError)

No migration with version number 20261111193133.

Si quieres quitar una migración, primero deshazla con db:rollback y después borra el fichero. Si ya la borraste, recupérala (por ejemplo, del historial de Git), deshazla y bórrala.

4. Editar una migración que ya han ejecutado otros. No da error, y por eso es peor: Rails no vuelve a ejecutar una migración que ya consta como aplicada, así que tu cambio no llega a la base de datos de tus compañeros ni a la de producción.

Una migración ya compartida no se edita: se crea otra que la corrija.

Si la migración solo existe en tu equipo, sí puedes deshacerla, editarla y volver a aplicarla.

Cuándo no usar una migración

Las migraciones cambian la estructura: tablas, columnas e índices. Para los datos, la guía oficial recomienda no usarlas:

  • Datos iniciales (las categorías de partida, un usuario de pruebas): van en db/seeds.rb y se cargan con bin/rails db:seed.
  • Corregir o transformar datos existentes (rellenar una columna nueva en un millón de filas, por ejemplo): la guía advierte de que mezclarlo con el esquema complica el rollback y puede bloquear tablas mucho tiempo, y propone tareas aparte, como la gema maintenance_tasks.

¿Vas a crear la tabla desde cero? Empieza por crear modelos en Ruby on Rails, que genera la migración por ti. Si dudas entre :string y :text para una columna, lo tienes en diferencia entre text y string. Y si aún no has conectado la base de datos, mira configurar la base de datos en Ruby on Rails.

¿La tabla apunta a otra? Las claves ajenas y belongs_to están en asociaciones.

Ejercicio de cinco minutos

  1. En una aplicación de prueba, genera AddLevelToCourses level:integer, aplícala y comprueba con db:migrate:status que está en up.
  2. Pásale db:migrate:redo y mira que db/schema.rb queda igual.
  3. Crea otra migración que cambie level a :string con change_column dentro de change. Aplícala, intenta deshacerla y lee el error. Arréglala con up y down hasta que redo funcione.

Fuentes

  • Guía de migraciones de Active Record (Rails 8.1.4.1): patrones del generador, qué operaciones se pueden deshacer en change (y que change_column no), up/down, db:migrate:redo, VERSION=, db:prepare, no editar migraciones ya compartidas y la recomendación de no cambiar datos en las migraciones (db/seeds.rb y maintenance_tasks).
  • Ejecutado el 11 de noviembre de 2026 con Ruby 3.4.12 y Rails 8.1.4.1 sobre SQLite (imagen oficial ruby:3.4 de Docker): todas las salidas del artículo, incluidos el error de change_column al deshacer, PendingMigrationError en una petición de desarrollo, la columna duplicada y el fichero borrado. Sobre db:prepare: la guía dice que no hace nada si la base de datos y sus tablas ya existen, pero ejecutándolo, y en el código de prepare_all de activerecord 8.1.4.1, aplica las migraciones pendientes. Con la base de datos inexistente, se ha comprobado que la crea y carga db/seeds.rb. STEP=3 y VERSION= se han comprobado en la guía.
  • Cambios respecto al original (Rails 5.2): ruby bin/rails se simplifica a bin/rails, y las capturas de la terminal se sustituyen por la salida en texto de Rails 8.1.