Migraciones en Ruby on Rails: crear, ejecutar y deshacer
¿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.rby se cargan conbin/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
- En una aplicación de prueba, genera
AddLevelToCourses level:integer, aplícala y comprueba condb:migrate:statusque está enup. - Pásale
db:migrate:redoy mira quedb/schema.rbqueda igual. - Crea otra migración que cambie
levela:stringconchange_columndentro dechange. Aplícala, intenta deshacerla y lee el error. Arréglala conupydownhasta queredofuncione.
Fuentes
- Guía de migraciones de Active Record (Rails 8.1.4.1): patrones del generador, qué operaciones se pueden deshacer en
change(y quechange_columnno),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.rbymaintenance_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.4de Docker): todas las salidas del artículo, incluidos el error dechange_columnal deshacer,PendingMigrationErroren una petición de desarrollo, la columna duplicada y el fichero borrado. Sobredb: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 deprepare_alldeactiverecord8.1.4.1, aplica las migraciones pendientes. Con la base de datos inexistente, se ha comprobado que la crea y cargadb/seeds.rb.STEP=3yVERSION=se han comprobado en la guía. - Cambios respecto al original (Rails 5.2):
ruby bin/railsse simplifica abin/rails, y las capturas de la terminal se sustituyen por la salida en texto de Rails 8.1.