Asociaciones en Ruby on Rails: belongs_to, has_many y joins
Las asociaciones en Ruby on Rails le dicen a Active Record cómo se relacionan dos modelos, y gracias a ellas haces un join en Rails sin escribir SQL: un usuario tiene una dirección, un post tiene muchos comentarios. En lugar de buscar a mano por identificadores, escribes post.comentarios y Rails hace la consulta.
Piensa en las fichas de una biblioteca: la ficha de cada préstamo lleva apuntado el número de socio. El préstamo «pertenece a» un socio (belongs_to) y el socio «tiene muchos» préstamos (has_many). El número apuntado es la clave foránea: una columna que guarda el id de la fila de otra tabla.
Todo el código de modelos y consultas se ha ejecutado con Ruby 4.0.9 y Active Record 8.1.4.1 sobre SQLite, y las salidas y las SQL que ves son las reales. Los generadores se han ejecutado en una aplicación Rails 8.1.4.1.
Los tipos de asociación
| Relación | Ejemplo | Modelo con la clave foránea | El otro modelo |
|---|---|---|---|
| Uno a uno (1:1) | Un usuario tiene una dirección | belongs_to :user |
has_one :address |
| Uno a muchos (1:N) | Un post tiene muchos comentarios | belongs_to :post |
has_many :comentarios |
| Muchos a muchos (N:M) | Un usuario está en muchos foros, y un foro tiene muchos usuarios | Tabla intermedia | has_many :through o has_and_belongs_to_many en ambos |
¿belongs_to o has_one?
En Rails, belongs_to declara que un modelo pertenece a otro: su tabla guarda la clave foránea que apunta al dueño, y has_one es el lado contrario. Las dos expresan una relación uno a uno. La diferencia es dónde está la clave foránea: va en la tabla del modelo que declara belongs_to.
class User < ApplicationRecord
belongs_to :account # la tabla users tiene la columna account_id
end
class Account < ApplicationRecord
has_one :user
end
Las tablas quedarían así (esquema simplificado):
CREATE TABLE users (
id bigint PRIMARY KEY,
account_id bigint, -- clave foránea
name varchar
);
CREATE TABLE accounts (
id bigint PRIMARY KEY,
name varchar
);
Uno a uno (1:1) con has_one: usuario y dirección
Un usuario solo puede tener una dirección postal.
- Crea los modelos.
- Añade la clave foránea a la tabla de direcciones.
- Ejecuta la migración.
- Declara la asociación en los dos modelos.
bin/rails generate model User name:string
bin/rails generate model Address street:string
bin/rails generate migration AddUserToAddresses user:references
La última orden genera esta migración (en Rails 8.1):
class AddUserToAddresses < ActiveRecord::Migration[8.1]
def change
add_reference :addresses, :user, null: false, foreign_key: true
end
end
Ejecútala:
bin/rails db:migrate
La base de datos ya tiene la columna, pero Active Record todavía no conoce la relación. Decláralo en los modelos:
class User < ApplicationRecord
has_one :address
end
class Address < ApplicationRecord
belongs_to :user
end
Ya puedes asociarlos desde cualquiera de los dos lados:
pepe = User.new(name: "Pepe")
pepe.address = Address.new(street: "Calle Ejemplo")
pepe.save # guarda los dos
User.last.address.street # => "Calle Ejemplo"
Si intentas guardar una dirección sin usuario, belongs_to lo impide:
huerfana = Address.new(street: "Calle Sin Dueño")
huerfana.save # => false
huerfana.errors.full_messages # => ["User must exist"]
Con has_one también tienes build_address, que crea la dirección ya enlazada al usuario, pero sin guardarla:
ana = User.create!(name: "Ana")
direccion = ana.build_address(street: "Calle Mayor")
direccion.user_id == ana.id # => true
direccion.new_record? # => true (aún no está en la base de datos)
Uno a muchos (1:N): post y comentarios
bin/rails generate model Post title:string
bin/rails generate model Comentario text:string post:references
bin/rails db:migrate
Con post:references el generador ya añade la clave foránea y el belongs_to :post en Comentario. Si el modelo ya existía, puedes añadirla después con bin/rails generate migration AddPostToComentarios post:references, como en el caso anterior. Completa el otro lado:
class Post < ApplicationRecord
has_many :comentarios, dependent: :destroy
end
class Comentario < ApplicationRecord
belongs_to :post
end
dependent: :destroy borra los comentarios cuando borras su post, para que no queden huérfanos. Las demás opciones están en Qué pasa al borrar.
post = Post.new(title: "Primer post")
post.comentarios << Comentario.new(text: "Comentario de prueba")
post.save
post.comentarios.create(text: "Otro comentario") # lo crea ya asociado
Post.last.comentarios.count # => 2
post.comentarios.build(text: "Sin guardar") # asociado, pero sin guardar
¿Qué hace Rails por debajo cuando escribes post.comentarios? Puedes verlo con to_sql, que devuelve la consulta sin ejecutarla:
puts post.comentarios.to_sql
SELECT "comentarios".* FROM "comentarios" WHERE "comentarios"."post_id" = 1
Es la ficha de la biblioteca en SQL: busca los comentarios que llevan apuntado el id del post.
Muchos a muchos (N:M): usuarios y foros
Aquí ninguna de las dos tablas puede guardar la clave foránea: un usuario está en muchos foros y un foro tiene muchos usuarios. Hace falta una tabla intermedia que apunte a las dos.
Opción 1: has_many :through
La tabla intermedia es un modelo más, Membership, así que puedes añadirle datos propios. Aquí, el rol de cada usuario en cada foro. User ya existe del apartado anterior; faltan el foro y la membresía:
bin/rails generate model Forum name:string
bin/rails generate model Membership user:references forum:references rol:string
bin/rails db:migrate
La última orden genera esta migración y este modelo (Rails 8.1.4.1):
class CreateMemberships < ActiveRecord::Migration[8.1]
def change
create_table :memberships do |t|
t.references :user, null: false, foreign_key: true
t.references :forum, null: false, foreign_key: true
t.string :rol
t.timestamps
end
end
end
class Membership < ApplicationRecord
belongs_to :user
belongs_to :forum
end
El generador solo escribe los belongs_to de Membership. En los otros dos modelos añades tú, primero con la asociación a la tabla intermedia y después con el through:
class User < ApplicationRecord
has_many :memberships
has_many :forums, through: :memberships
end
class Forum < ApplicationRecord
has_many :memberships
has_many :users, through: :memberships
end
through: :memberships significa «para llegar a los foros, pasa por las membresías». Ahora puedes crear la relación de dos formas:
luis = User.create!(name: "Luis")
rails = Forum.create!(name: "Rails")
ruby = Forum.create!(name: "Ruby")
luis.memberships.create!(forum: rails, rol: "moderador") # con datos propios
luis.forums << ruby # crea la membresía sola
luis.forums.map(&:name) # => ["Rails", "Ruby"]
Membership.where(user: luis).pluck(:forum_id, :rol)
# => [[1, "moderador"], [2, nil]]
luis.forums << ruby crea la fila de memberships por ti, pero sin rol. Si la tabla intermedia tiene datos que importan, créala de forma explícita, como en la primera línea.
La SQL de luis.forums muestra el join con la tabla intermedia:
puts luis.forums.to_sql
SELECT "forums".* FROM "forums" INNER JOIN "memberships" ON "forums"."id" = "memberships"."forum_id" WHERE "memberships"."user_id" = 1
Opción 2: has_and_belongs_to_many
Si la tabla intermedia solo une las dos y no necesitas un modelo para ella, crea una tabla JOIN:
bin/rails generate migration CreateJoinTableUsersForums users forums
La migración generada trae los índices comentados. Descoméntalos para que las búsquedas sean rápidas:
class CreateJoinTableUsersForums < ActiveRecord::Migration[8.1]
def change
create_join_table :users, :forums do |t|
t.index [:user_id, :forum_id]
t.index [:forum_id, :user_id]
end
end
end
create_join_table crea la tabla forums_users, con los dos nombres en orden alfabético y solo las columnas user_id y forum_id, sin id. Tras bin/rails db:migrate, declara la asociación en ambos modelos:
class User < ApplicationRecord
has_and_belongs_to_many :forums
end
class Forum < ApplicationRecord
has_and_belongs_to_many :users
end
luis.forums << Forum.find_by(name: "Ruby") # añade un foro a Luis
Forum.find_by(name: "Ruby").users # usuarios de ese foro
puts luis.forums.to_sql
SELECT "forums".* FROM "forums" INNER JOIN "forums_users" ON "forums"."id" = "forums_users"."forum_id" WHERE "forums_users"."user_id" = 1
¿Cuál elegir?
La guía oficial recomienda has_many :through cuando la tabla intermedia necesita columnas propias, validaciones o callbacks, o representa algo con entidad propia (una membresía, una matrícula, una suscripción). has_and_belongs_to_many sirve para uniones simples sin nada más. Si dudas, conviene has_many :through, porque te deja crecer: añadir una columna a memberships es una migración; pasar de has_and_belongs_to_many a through obliga a cambiar la tabla y los modelos.
has_one :through: llegar a un registro pasando por otro
Hay quien busca «belongs_to through», pero esa opción no existe. Lo que existe es has_one :through: una relación uno a uno a través de un modelo intermedio. Por ejemplo, si cada post tiene un autor (belongs_to :user), cada comentario puede llegar al autor del post:
class Post < ApplicationRecord
belongs_to :user
has_many :comentarios
end
class Comentario < ApplicationRecord
belongs_to :post
has_one :autor, through: :post, source: :user
end
source: :user le dice a Rails cómo se llama la asociación en Post, porque aquí la has llamado autor.
comentario.autor.name # => "Luis"
puts Comentario.joins(:autor).to_sql
SELECT "comentarios".* FROM "comentarios" INNER JOIN "posts" ON "posts"."id" = "comentarios"."post_id" INNER JOIN "users" ON "users"."id" = "posts"."user_id"
Joins en Rails: consultar a través de las asociaciones
Una vez declaradas las asociaciones, también sirven para filtrar. joins hace un INNER JOIN: une cada post con sus comentarios y se queda solo con los posts que tienen alguno.
puts Post.joins(:comentarios).to_sql
Post.joins(:comentarios).map(&:title)
Post.joins(:comentarios).distinct.map(&:title)
SELECT "posts".* FROM "posts" INNER JOIN "comentarios" ON "comentarios"."post_id" = "posts"."id"
["Primer post", "Primer post"]
["Primer post"]
El post sale dos veces porque tiene dos comentarios: el join devuelve una fila por cada pareja post-comentario. Con distinct lo tienes una sola vez.
Lo habitual es combinar joins con where sobre la tabla unida. Fíjate en que la clave del hash es el nombre de la tabla (comentarios):
consulta = Post.joins(:comentarios).where(comentarios: { text: "Otro comentario" })
puts consulta.to_sql
SELECT "posts".* FROM "posts" INNER JOIN "comentarios" ON "comentarios"."post_id" = "posts"."id" WHERE "comentarios"."text" = 'Otro comentario'
Con has_many :through funciona igual, y Rails encadena los dos joins:
puts User.joins(:memberships).where(memberships: { rol: "moderador" }).to_sql
puts User.joins(:forums).where(forums: { name: "Ruby" }).to_sql
SELECT "users".* FROM "users" INNER JOIN "memberships" ON "memberships"."user_id" = "users"."id" WHERE "memberships"."rol" = 'moderador'
SELECT "users".* FROM "users" INNER JOIN "memberships" ON "memberships"."user_id" = "users"."id" INNER JOIN "forums" ON "forums"."id" = "memberships"."forum_id" WHERE "forums"."name" = 'Ruby'
Si una consulta así se repite, dale nombre con un scope: lo tienes en Scopes en Ruby on Rails.
Los que no tienen ninguno: left_outer_joins y where.missing
joins deja fuera a los posts sin comentarios. Para encontrar justo esos, hace falta un LEFT OUTER JOIN, que conserva todos los posts aunque no tengan pareja, y quedarse con los que no la tienen:
sin_comentarios = Post.left_outer_joins(:comentarios).where(comentarios: { id: nil })
puts sin_comentarios.to_sql
sin_comentarios.map(&:title)
SELECT "posts".* FROM "posts" LEFT OUTER JOIN "comentarios" ON "comentarios"."post_id" = "posts"."id" WHERE "comentarios"."id" IS NULL
["Post sin comentarios"]
Post.where.missing(:comentarios) genera exactamente la misma SQL y se lee mejor. Su contrario, where.associated(:comentarios), devuelve los posts que tienen al menos un comentario. Por debajo es un INNER JOIN, así que repite el post como joins (["Primer post", "Primer post"]); añade distinct para tenerlo una vez.
includes y el problema de las N+1 consultas
Recorrer posts y pedir los comentarios de cada uno parece inocente:
Post.all.each { |post| post.comentarios.map(&:text) }
SELECT "posts".* FROM "posts"
SELECT "comentarios".* FROM "comentarios" WHERE "comentarios"."post_id" = ?
SELECT "comentarios".* FROM "comentarios" WHERE "comentarios"."post_id" = ?
Una consulta para los posts y una más por cada post: con dos posts son tres; con cien, ciento una. Es el problema de las N+1 consultas. includes carga todos los comentarios de golpe:
Post.includes(:comentarios).each { |post| post.comentarios.map(&:text) }
SELECT "posts".* FROM "posts"
SELECT "comentarios".* FROM "comentarios" WHERE "comentarios"."post_id" IN (?, ?)
Dos consultas, tengas los posts que tengas. Las ? son los valores, que Active Record pasa aparte (bind parameters); to_sql los muestra ya escritos.
Si además filtras por la tabla incluida, includes cambia de estrategia y hace un único LEFT OUTER JOIN:
Post.includes(:comentarios).where(comentarios: { text: "Otro comentario" }).to_a
SELECT "posts"."id" AS t0_r0, "posts"."title" AS t0_r1, "comentarios"."id" AS t1_r0, "comentarios"."text" AS t1_r1, "comentarios"."post_id" AS t1_r2 FROM "posts" LEFT OUTER JOIN "comentarios" ON "comentarios"."post_id" = "posts"."id" WHERE "comentarios"."text" = ?
| Método | Qué hace | Para qué |
|---|---|---|
joins |
INNER JOIN, no carga la asociación |
Filtrar por la otra tabla |
left_outer_joins |
LEFT OUTER JOIN, no carga la asociación |
Incluir también los que no tienen pareja |
includes |
Carga la asociación en una consulta aparte o con un join | Evitar N+1 cuando vas a usar la asociación |
preload |
Siempre una consulta por asociación | Forzar consultas separadas |
eager_load |
Siempre un LEFT OUTER JOIN |
Forzar una sola consulta |
La tabla es un resumen nuestro de la guía oficial de consultas de Active Record.
Qué pasa al borrar: la opción dependent
Cuando borras un post, ¿qué pasa con sus comentarios? Lo decides con dependent: en el has_many (o en el has_one). Este es el resultado de borrar un post con dos comentarios con cada opción, y la SQL que lanza Rails:
| Opción | SQL que se ejecuta | Resultado |
|---|---|---|
:destroy |
Carga los comentarios y lanza un DELETE por cada uno; después borra el post |
Se borran el post y sus dos comentarios. Se ejecutan los callbacks de cada comentario |
:delete_all |
Un solo DELETE FROM "comentarios" WHERE "comentarios"."post_id" = ? |
Se borran el post y sus dos comentarios, sin callbacks de los comentarios |
:nullify |
UPDATE "comentarios" SET "post_id" = ? (a NULL) |
Se borra el post; los comentarios quedan sin post |
:restrict_with_error |
Solo un SELECT que comprueba si hay hijos; ningún DELETE |
destroy devuelve false y el post tiene el error Cannot delete record because dependent comentarios exist |
:restrict_with_exception |
Solo un SELECT que comprueba si hay hijos; ningún DELETE |
Lanza ActiveRecord::DeleteRestrictionError |
Sin dependent |
Solo el DELETE del post |
Rails no toca los comentarios. Con clave foránea en la base de datos, el borrado falla con ActiveRecord::InvalidForeignKey |
La salida real de :destroy y de :delete_all:
== dependent: :destroy
SELECT "comentarios".* FROM "comentarios" WHERE "comentarios"."post_id" = ?
DELETE FROM "comentarios" WHERE "comentarios"."id" = ?
DELETE FROM "comentarios" WHERE "comentarios"."id" = ?
DELETE FROM "posts" WHERE "posts"."id" = ?
== dependent: :delete_all
DELETE FROM "comentarios" WHERE "comentarios"."post_id" = ?
DELETE FROM "posts" WHERE "posts"."id" = ?
Cómo elegir:
:destroysi los comentarios tienen callbacks o asociaciones propias que también hay que limpiar. Es más lento con muchos registros, porque los carga uno a uno. Los callbacks se explican en Callbacks en Ruby on Rails.:delete_allsi son muchos y no tienen lógica al borrarse.:nullifysi los hijos tienen sentido sin el padre. La columna debe admitirNULL(sinnull: falseen la migración), y elbelongs_tonecesitaoptional: truepara poder volver a guardar esos hijos.:restrict_with_errorsi no se debe poder borrar algo que todavía tiene hijos, y quieres mostrar el error en un formulario como el de una validación.
Existe también :destroy_async, que borra los hijos en un trabajo en segundo plano. La documentación oficial advierte de que no se use si la asociación está respaldada por claves foráneas en la base de datos.
Errores frecuentes
User must existal guardar. Falta el registro delbelongs_to. Asígnalo antes de guardar o, si de verdad es opcional, usaoptional: true.belongs_toen el modelo equivocado. Va donde está la columna_id. Si ponesbelongs_to :comentarioenPost, Rails buscará una columnacomentario_idenposts, y al asignar un comentario verásActiveModel::MissingAttributeError: can't write unknown attribute `comentario_id`.- Plural y singular.
belongs_to :postyhas_one :addressvan en singular;has_many :comentarios, en plural. Conbelongs_to :posts, Rails busca una clasePostsy falla conNameError: Missing model class Posts. - Olvidar el primer
has_manydelthrough.has_many :forums, through: :membershipsnecesitahas_many :membershipsen el mismo modelo, y declarado antes. Si falta, verásHasManyThroughAssociationNotFoundError; si está después,HasManyThroughOrderError. - Duplicados con
joins. Una fila por cada pareja: añadedistinctsi quieres cada registro una vez. - N+1 sin darte cuenta. Si en el log de desarrollo ves la misma consulta repetida con distinto
id, añadeincludes. - Borrar sin pensar en los hijos. Sin
dependent, Rails no hace nada con ellos: o la base de datos rechaza el borrado o quedan filas que apuntan a un registro que ya no existe.
Pruébalo sin crear una aplicación
Para experimentar con asociaciones no hace falta un proyecto Rails: basta Active Record con SQLite en memoria. Guarda esto como asociaciones.rb:
require "active_record"
ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
# En una aplicación Rails esto ya viene activado; con Active Record suelto, no.
ActiveRecord::Base.belongs_to_required_by_default = true
ActiveRecord::Schema.define do
create_table(:posts) { |t| t.string :title }
create_table :comentarios do |t|
t.string :text
t.references :post, null: false, foreign_key: true
end
end
class Post < ActiveRecord::Base
has_many :comentarios, dependent: :destroy
end
class Comentario < ActiveRecord::Base
belongs_to :post
end
post = Post.create!(title: "Primer post")
post.comentarios.create!(text: "Hola")
Post.create!(title: "Post sin comentarios")
puts Post.joins(:comentarios).to_sql
puts Post.where.missing(:comentarios).map(&:title).inspect
Y ejecútalo con Docker, sin instalar Ruby:
docker run --rm -v "$PWD":/app -w /app ruby:latest \
sh -c 'gem install activerecord:8.1.4.1 sqlite3 && ruby asociaciones.rb'
Las últimas líneas de la salida:
SELECT "posts".* FROM "posts" INNER JOIN "comentarios" ON "comentarios"."post_id" = "posts"."id"
["Post sin comentarios"]
Dentro de una aplicación, lo mismo se prueba en la consola de Rails con bin/rails console.
La clave foránea vive en la tabla del belongs_to.
Sigue leyendo
- Crear modelos en Ruby on Rails
- Migraciones en Ruby on Rails
- Active Record Validations: validar campos en Rails
- Scopes en Ruby on Rails
- CRUD desde la consola de Rails
Fuentes
Consultadas el 9 de noviembre de 2026, en su versión para Rails 8.1.4.1:
- Active Record Associations, guía oficial de Rails: tipos de asociación,
has_one :throughy cuándo elegirhas_many :throughohas_and_belongs_to_many. - Active Record Query Interface, guía oficial:
joins,left_outer_joins,where.missing,where.associated,includes,preload,eager_loady el problema de las N+1 consultas. - Active Record Migrations, guía oficial:
add_referencey el tipo de la clave foránea. - Notas de la versión 5.0 de Rails:
belongs_toobligatorio por defecto y las tareas de Rake a través debin/rails. - API de
ActiveRecord::Associations::ClassMethods: las opciones dedependentysource.
Ejecutado en noviembre de 2026 en Docker con la imagen ruby:latest (Ruby 4.0.9), Active Record 8.1.4.1 y sqlite3 2.10.2, con SQLite en memoria: las tres relaciones, build_address, el error User must exist, la pluralización, has_many :through, has_and_belongs_to_many, has_one :through, todas las consultas con su to_sql, las N+1 con y sin includes, las seis variantes de dependent, los errores de la lista y el script de «Pruébalo sin crear una aplicación». Los generadores y migraciones se ejecutaron en una aplicación Rails 8.1.4.1 con SQLite. Los identificadores (= 1, [1, "moderador"]) dependen de los datos de cada prueba.