relations

Documentation

Overview

Package relations implements model relationships with eager-loading. Relationships are defined as free functions that take the parent and a connection and return a *Relation; the relation can then be loaded synchronously (Load) or attached to a batch via LoadMany.

Index

• type Kind
• type Relation
  • func BelongsToManyOf(conn *database.Connection, parent, children any, ...) *Relation
  • func BelongsToOf(conn *database.Connection, parent any, owner any, foreignKey string) *Relation
  • func HasManyOf(conn *database.Connection, parent any, children any, parentFK string) *Relation
  • func HasOneOf(conn *database.Connection, parent any, child any, parentFK string) *Relation
  • func MorphManyOf(conn *database.Connection, parent, children any, morphName, morphValue string) *Relation
  • func (r *Relation) Load(ctx context.Context) error
  • func (r *Relation) LoadMany(ctx context.Context, parents []any, assignFn func(parent any, children any)) error

Types

type Kind

type Kind int

Kind enumerates relationship kinds.

const (
	HasOne Kind = iota
	HasMany
	BelongsTo
	BelongsToMany
	MorphOne
	MorphMany
)

type Relation

type Relation struct {
	Kind           Kind
	Conn           *database.Connection
	ParentModel    any
	ChildSlicePtr  any // *[]Child (HasMany / BelongsToMany / MorphMany) OR *Child for one-row kinds.
	ForeignKey     string
	OwnerKey       string
	PivotTable     string // for BelongsToMany
	PivotForeignFK string // pivot FK to parent
	PivotRelatedFK string // pivot FK to child
	MorphType      string // for polymorphic: column holding child model type
	MorphID        string // for polymorphic: column holding child model id
	MorphValue     string // expected type string in MorphType column
}

Relation describes a relationship from a parent model to one or more children.

func BelongsToManyOf

func BelongsToManyOf(conn *database.Connection, parent, children any, pivot, parentFK, relatedFK string) *Relation

BelongsToManyOf builds a many-to-many relation through pivot table.

func BelongsToOf

func BelongsToOf(conn *database.Connection, parent any, owner any, foreignKey string) *Relation

BelongsToOf builds a BelongsTo relation.

func HasManyOf

func HasManyOf(conn *database.Connection, parent any, children any, parentFK string) *Relation

HasManyOf builds a HasMany relation: parent.id == children.<parentFK>.

func HasOneOf

func HasOneOf(conn *database.Connection, parent any, child any, parentFK string) *Relation

HasOneOf builds a HasOne relation.

func MorphManyOf

func MorphManyOf(conn *database.Connection, parent, children any, morphName, morphValue string) *Relation

MorphManyOf builds a polymorphic HasMany relation; the child rows must have `morph_type` and `morph_id` columns.

func (*Relation) Load

func (r *Relation) Load(ctx context.Context) error

Load executes the relation against a single parent and writes the result into the relation's destination pointer.

func (*Relation) LoadMany

func (r *Relation) LoadMany(ctx context.Context, parents []any, assignFn func(parent any, children any)) error

LoadMany loads the relation for a batch of parents in one query and distributes the result back via the provided assignFn callback. assignFn receives the parent pointer and the matching children slice (any).