Relationships, and the forms they generate

A model on its own is a spreadsheet. The moment a task belongs to a project and carries tags, you have the thing that makes applications hard: two tables that must agree, a form that has to offer the right options, a query that must not run once per row, and a JSON shape the frontend can rely on.

Grit has four relationship shapes. This chapter is what each one writes, and where each one bites.

The four shapes, and the question each answers

• belongs_to
• This row points at one other row. A task has a project
• one_to_one
• The same, but only one row may point at each target. A user has one profile
• many_to_many
• Both sides have many. A task has tags, a tag has tasks
• --items
• A child that exists only inside its parent. An invoice has line items

The fourth is not a field type, and the difference is worth naming early: an--items child has no life of its own. You do not browse line items; you edit an invoice. Everything else is a relation between two things that each exist.

belongs_to, and everything it writes

grit generate resource Task \
  --fields "title:string, project:belongs_to:Project"

The related model is the third part, and it is optional when the field name already names it: project:belongs_to finds Project. Spell it out when the field is called something else, which is the usual case for people:author:belongs_to:User.

In the model you get two things, not one:

type Task struct {
    ID        uint     `json:"id" gorm:"primaryKey"`
    Title     string   `json:"title"`
    ProjectID uint     `json:"project_id" gorm:"index"`
    Project   *Project `gorm:"foreignKey:ProjectID"
                        json:"project,omitempty"`
}

ProjectID is the column the database knows about, indexed because every listing filters on it. Project is the association GORM fills in when asked, and it is a *pointer with omitempty*.

The service preloads it, so a list of tasks arrives with its projects:

db.Preload("Project").Find(&tasks)

That is chapter twenty two's N+1 solved by default: one query for tasks, one for the projects they reference, rather than one per row. You get it without asking, which is also why it is worth knowing it is there when a list of twelve columns suddenly reads from five tables.

The admin dropdown, and the label it shows

The form field for a belongs_to is a searchable dropdown, and the thing that makes it usable is what it displays. It is not the ID, and it is not a field called whatever came first. The generator looks for a label column on the related model, in this order:

name, title, label, subject, number, code, reference, email

The first one that exists wins. A Project shows its name, an Invoice shows its number, and a User with none of those falls back to its email, which is the reason the fallback list ends there rather than at code.

one_to_one is belongs_to plus one index

grit generate resource Profile \
  --fields "bio:text, user:one_to_one:User"

The generated code differs from belongs_to in exactly one place: the foreign key gets a unique index rather than an ordinary one.

That single line is what makes the name true. Without it, "one profile per user" is a comment, because the database would happily accept a second row pointing at the same user, and the second one usually arrives from a retried request rather than from a user doing something strange.

A relation pointing at itself is a tree

grit generate field Category parent:belongs_to:Category

Electronics above Cameras above Lenses, in one table. Two details differ from an ordinary relation, and both were found the hard way.

The association must be a pointer. Go rejects a struct that contains itself by value: invalid recursive type. A generated project with a self-reference did not compile at all before this was handled.

The foreign key must be nullable. GORM creates a real foreign key constraint, and a root category has no parent, so the column has to hold something the constraint accepts. SQL has exactly one such value, and it is NULL.

ERROR: insert or update on table "categories" violates
foreign key constraint "fk_categories_children"

For a real hierarchy, the flag does more than the field:

grit generate resource Category --fields "name:string" --tree

That gives the self-referential parent plus a materialized path, a depth, a sibling order, the tree queries and a move endpoint. The difference matters when you need "everything under Electronics" as one query rather than as recursion in application code.

many_to_many, and the table you did not name

grit generate resource Task \
  --fields "title:string, tags:many_to_many:Tag"

The related model is required here. There is nothing to infer from, becausetags is a plural of the field, not of the model.

The model gets a slice and no foreign key, because the keys live in a third table:

Tags []Tag `gorm:"many2many:tasks_tags" json:"tags"`

The join table is named from the owning model and the field: tasks_tags. GORM creates and maintains it, and you do not get a model for it.

In the admin this renders as a multi-select picker, and in JSON it is an array, which means a create or update sends IDs:

{ "title": "Fix the leak", "tag_ids": [3, 7] }

Line items: a child inside its parent

grit generate resource Invoice \
  --fields "number:string, client:belongs_to:Client" \
  --items "InvoiceItem:description:string,qty:int,unit:money"

The child is generated fully, and the parent's form gets a line-items table: add a row, remove a row, totals that update. That is a component people build by hand for a week.

The part worth understanding is the update, because it is not what you would write first:

// Inside the same transaction as the parent update
tx.Where("invoice_id = ?", item.ID).
    Delete(&models.InvoiceItem{})
tx.Create(&rows)

The children are deleted and recreated rather than diffed.

What relationships cost on a list page

Three consequences that surprise people, all of them from chapter thirty two's whitelists:

You cannot sort by a relation. The sortable list contains columns, andproject.name is not a column of tasks. Sorting by a related field needs a join the generated query does not make. Sort by project_id if order matters, or denormalise the name onto the row if it matters a lot.

You filter by the key, not the label. ?project_id=4 works. ?project=Apollodoes not, unless you add it.

Search does not cross the relation. Searching tasks searches the task's own searchable columns. Finding "every task whose project is named Apollo" is a query you write.

Choosing well

Two questions settle most modelling arguments.

Is the other side a real thing, or a word? A status is a word: select, not a relation. A supplier is a thing: a relation. The giveaway is whether anybody would ever want to edit it, list it, or attach anything else to it.

Does the link itself carry data? If yes, it is a model, not amany_to_many.

grit new timetable
cd timetable

grit generate resource Teacher --fields "name:string, email:email"
grit generate resource Room --fields "code:string, seats:int"
grit generate resource Course \
  --fields "title:string, teacher:belongs_to:Teacher"

docker compose up -d db

Assignment

Commit your work with the message Relationships - Assignment One, exactly as written, so the leaderboard can score it.