Nivel inicial14 min de lectura · Publicado el

Asociaciones en Ruby on Rails: belongs_to, has_many y joins

Asociaciones en Ruby on Rails: tres fichas de préstamo con el número de socio apuntado (belongs_to) que señalan a la ficha del socio (has_many). La clave va en belongs_torubentejera.com Sociohas_manynº socionº socionº sociobelongs_to
Cada préstamo lleva apuntado el número de socio: esa es la clave foránea. El préstamo pertenece a un socio (belongs_to) y el socio tiene muchos préstamos (has_many).

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
Los tres tipos de asociación con sus tablas; la flecha va de la clave foránea a la tabla a la que apunta. Uno a uno: addresses tiene user_id, que apunta a users; User declara has_one :address y Address, belongs_to :user. Uno a muchos: comentarios tiene post_id, que apunta a posts; Post declara has_many :comentarios y Comentario, belongs_to :post. Muchos a muchos: la tabla intermedia memberships tiene user_id y forum_id, que apuntan a users y a forums, y una columna propia, rol; Membership declara belongs_to :user y belongs_to :forum, y User y Forum, has_many con through: :memberships.
Las tablas de los ejemplos de esta guía. En ámbar, la clave foránea, y la flecha va de ella a la tabla a la que apunta; debajo de cada tabla, lo que declara su modelo. En muchos a muchos, la tabla intermedia es la que guarda las dos claves.

¿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.

  1. Crea los modelos.
  2. Añade la clave foránea a la tabla de direcciones.
  3. Ejecuta la migración.
  4. 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:

  • :destroy si 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_all si son muchos y no tienen lógica al borrarse.
  • :nullify si los hijos tienen sentido sin el padre. La columna debe admitir NULL (sin null: false en la migración), y el belongs_to necesita optional: true para poder volver a guardar esos hijos.
  • :restrict_with_error si 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 exist al guardar. Falta el registro del belongs_to. Asígnalo antes de guardar o, si de verdad es opcional, usa optional: true.
  • belongs_to en el modelo equivocado. Va donde está la columna _id. Si pones belongs_to :comentario en Post, Rails buscará una columna comentario_id en posts, y al asignar un comentario verás ActiveModel::MissingAttributeError: can't write unknown attribute `comentario_id` .
  • Plural y singular. belongs_to :post y has_one :address van en singular; has_many :comentarios, en plural. Con belongs_to :posts, Rails busca una clase Posts y falla con NameError: Missing model class Posts.
  • Olvidar el primer has_many del through. has_many :forums, through: :memberships necesita has_many :memberships en el mismo modelo, y declarado antes. Si falta, verás HasManyThroughAssociationNotFoundError; si está después, HasManyThroughOrderError.
  • Duplicados con joins. Una fila por cada pareja: añade distinct si 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ñade includes.
  • 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

Fuentes

Consultadas el 9 de noviembre de 2026, en su versión para Rails 8.1.4.1:

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.