Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Databases and GORM

Relationships and Preloading in GORM

Model has-one, has-many, belongs-to and many-to-many relations in GORM, load them with Preload and Joins, avoid the N+1 query problem and return nested JSON from Gin.

Real data is connected: an author has many posts, a post belongs to an author and has many tags, and tags belong to many posts. Relational databases express this with foreign keys, and GORM lets you describe the links in your structs. Used well, relations make handlers short. Used carelessly, they cause the N+1 query problem, one of the most common performance bugs in web apps. This lesson covers the four relation types and how to load them efficiently.

The GORM code is read-only (it does not run here). The runnable examples demonstrate the data-access patterns with in-memory tables and a query counter, so you can measure the N+1 effect yourself. Review GORM Setup and Models for the basics.

The four relation types

Go
type Author struct {
	ID    uint
	Name  string
	Posts []Post          // has many: Post.AuthorID points back here
	Profile Profile       // has one:  Profile.AuthorID
}

type Profile struct {
	ID       uint
	AuthorID uint         // foreign key
	Bio      string
}

type Post struct {
	ID       uint
	Title    string
	AuthorID uint         // foreign key
	Author   Author       // belongs to
	Tags     []Tag `gorm:"many2many:post_tags;"` // many to many via a join table
}

type Tag struct {
	ID    uint
	Label string
	Posts []Post `gorm:"many2many:post_tags;"`
}
  • Has many: the other table holds the key. Author has many Post because posts.author_id exists.
  • Has one: like has many, but a single value. Author has one Profile.
  • Belongs to: this table holds the key. A Post belongs to an Author through AuthorID.
  • Many to many: GORM creates and uses the join table post_tags(post_id, tag_id).

GORM finds the keys by naming convention: field AuthorID plus a field Author. When your names differ, use tags such as gorm:"foreignKey:WriterID". AutoMigrate(&Author{}, &Profile{}, &Post{}, &Tag{}) creates the tables, foreign keys and the join table.

Creating with associations

Creating a parent with children inserts everything in one go, inside a transaction:

Go
author := Author{
	Name:  "Ada",
	Posts: []Post{{Title: "Hello"}, {Title: "Gin and GORM"}},
}
db.Create(&author) // inserts the author, then both posts with author_id set

To link existing rows, use the association API: db.Model(&post).Association("Tags").Append(&tag), Replace(...), Delete(...), and Count().

Loading relations: nothing is loaded by default

A plain Find(&posts) leaves Author and Tags empty. You ask for them explicitly:

Go
var posts []Post
db.Preload("Author").Preload("Tags").Find(&posts)

Preload runs one extra query per relation (SELECT * FROM authors WHERE id IN (1,2,3)), then attaches the results in memory. That is 3 queries for the whole list, no matter how many posts. Variations:

Go
db.Preload("Posts", "published = ?", true).Find(&authors)        // condition on the relation
db.Preload("Posts", func(tx *gorm.DB) *gorm.DB {
	return tx.Order("created_at DESC").Limit(5)                // note: limit applies to the whole preload!
}).Find(&authors)
db.Preload("Posts.Tags").Find(&authors)                          // nested
db.Preload(clause.Associations).Find(&posts)                     // every direct relation
db.Joins("Author").Find(&posts)                                  // one query with a LEFT JOIN, for belongs-to / has-one

Use Joins when you also want to filter or sort by the related table (Where("Author.name = ?", ...)) and the relation is single-valued. Use Preload for has-many and many-to-many, where a join would repeat parent rows.

Seeing the N+1 problem

N+1 happens when you load a list (1 query) and then touch a relation for each item (N queries). In Go it usually hides in a loop:

Go
db.Find(&posts)                                  // 1 query
for i := range posts {
	db.First(&posts[i].Author, posts[i].AuthorID) // N more queries!
}

Each query has network latency (often 0.5 to 2 ms to a database on the same network), so 200 posts cost 200 round trips. The following stand-in simulates a database that counts queries. It performs the lookup both ways:

Go N+1 queries versus one batched lookup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Nine posts cost 10 queries one way and 2 the other; with 1,000 posts it is 1,001 versus 2. That is exactly what Preload("Author") does for you.

Nested JSON in Gin

Once relations are loaded, c.JSON encodes them as nested objects, using the json tags on the related structs. Beware cycles: Author.Posts[0].Author points back to the author, and the JSON encoder would recurse forever if both sides were loaded. Break the loop with json:"-" on the back-reference or, better, return purpose-built response types:

Go
type PostResponse struct {
	ID     uint     `json:"id"`
	Title  string   `json:"title"`
	Author string   `json:"author"`
	Tags   []string `json:"tags"`
}

func toResponse(p Post) PostResponse {
	r := PostResponse{ID: p.ID, Title: p.Title, Author: p.Author.Name}
	for _, t := range p.Tags {
		r.Tags = append(r.Tags, t.Label)
	}
	return r
}

The mapping function also controls what you expose, and keeps your API stable when the schema changes.

Go Map loaded relations to a response type

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Notice Tags: []string{} for the untagged post: it encodes as [], not null. Front-end code usually prefers an empty array.

Constraints and cascades

Foreign keys protect integrity: you cannot insert a post for a missing author. When deleting, decide what happens to children with OnDelete:

Go
Posts []Post `gorm:"constraint:OnDelete:CASCADE;"`

CASCADE deletes the posts with the author; SET NULL keeps them without an author; the default refuses the delete. Another option is db.Select("Posts").Delete(&author), which deletes the association rows explicitly. With soft deletes (DeletedAt), children are not removed automatically.

Common mistakes

  • Looping and querying inside the loop (N+1). Use Preload or one WHERE id IN (...) query.
  • Forgetting that relations are empty until preloaded.
  • Returning models with back-references and creating JSON cycles.
  • Using Preload plus a Limit inside it expecting "five per parent": the limit applies to the whole preload query.
  • Preloading every relation everywhere, which loads far more data than the endpoint needs.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a one-to-many Author to Post relation, which table holds the foreign key?

    The many side stores the key: posts.author_id points to authors.id.
  2. 2. How many queries does db.Preload("Author").Find(&posts) run for the posts and their authors?

    One query for posts and one batched IN query for the authors, regardless of the number of posts.
  3. 3. What is the N+1 problem?

    One query for the list plus N queries in a loop. Batching or joining removes it.
  4. 4. Which tag creates a many-to-many relation?

    many2many names the join table that stores the pairs of keys.
  5. 5. Why map models to response structs before c.JSON?

    Response types avoid recursive references and keep the API independent of the table structure.

Summary

  • Describe relations with fields and keys: has one, has many, belongs to, many2many.
  • Relations load only on request: Preload for collections (one extra query each), Joins for single-valued relations and filtering.
  • N+1 is a loop of queries; batch with IN or Preload.
  • Use response structs for JSON, decide delete behaviour with constraints, and preload only what you need.

Next: Transactions, Hooks and Migrations