Documentation
¶
Overview ¶
Package edge provides fluent builders for defining entity relationships in Velox ORM.
Edges define relationships between entities. They determine how entities are connected in the database through foreign keys and join tables.
Edge Types ¶
There are two primary edge types:
- edge.To: Defines the association (forward direction)
- edge.From: Defines the back-reference (inverse direction)
Relationship Cardinality ¶
Relationships are determined by the Unique() modifier:
// One-to-Many (default): User has many Posts
edge.To("posts", Post.Type)
// One-to-One: User has one Profile
edge.To("profile", Profile.Type).Unique()
// Many-to-One: Post belongs to User
edge.From("author", User.Type).Ref("posts").Unique()
// Many-to-Many: User has many Groups
edge.To("groups", Group.Type)
Bidirectional Edges ¶
Most edges are bidirectional, requiring edges on both entities:
// User schema
func (User) Edges() []velox.Edge {
return []velox.Edge{
edge.To("posts", Post.Type), // User -> Posts (O2M)
}
}
// Post schema
func (Post) Edges() []velox.Edge {
return []velox.Edge{
edge.From("author", User.Type). // Post -> User (M2O)
Ref("posts").
Unique(),
}
}
Edge Options ¶
Edges support various configuration options:
edge.To("comments", Comment.Type).
Required(). // Edge is required
Immutable(). // Cannot be changed after creation
Comment("Post comments")
Edge Fields (Foreign Keys) ¶
You can expose the foreign key as a field:
// In User schema fields
field.Int64("department_id").Optional()
// In User schema edges
edge.From("department", Department.Type).
Ref("employees").
Field("department_id").
Unique()
Foreign Key Actions ¶
Control what happens when referenced entities are deleted:
import "github.com/syssam/velox/dialect/sqlschema"
edge.To("posts", Post.Type).
Annotations(sqlschema.OnDelete(sqlschema.Cascade))
Available actions:
- sqlschema.Cascade: Delete related entities
- sqlschema.SetNull: Set foreign key to NULL
- sqlschema.Restrict: Prevent deletion
- sqlschema.NoAction: Database default
- sqlschema.SetDefault: Set to default value
Through Edges (Join Tables) ¶
For M2M relationships with additional fields:
// Define edge through a join table entity
edge.To("groups", Group.Type).
Through("memberships", Membership.Type)
Self-Referential Edges ¶
Entities can reference themselves:
// User has followers (other Users)
edge.To("followers", User.Type)
edge.To("following", User.Type)
Storage Key Customization ¶
Customize the foreign key column name:
edge.From("owner", User.Type).
Ref("pets").
Unique().
StorageKey(edge.Column("user_id"))
For M2M edges, customize the join table:
edge.To("groups", Group.Type).
StorageKey(
edge.Table("user_groups"),
edge.Columns("user_id", "group_id"),
)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Annotation ¶
type Annotation struct {
// The StructTag option allows overriding the struct-tag
// of the `Edges` field in the generated entity. For example:
//
// edge.Annotation{
// StructTag: `json:"pet_edges"`
// }
//
StructTag string
}
Annotation is a builtin schema annotation for configuring the edges' behavior in codegen.
func (Annotation) Merge ¶
func (a Annotation) Merge(other schema.Annotation) schema.Annotation
Merge implements the schema.Merger interface.
type Descriptor ¶
type Descriptor struct {
Tag string // struct tag.
Type string // edge type.
Name string // edge name.
Field string // edge field name (e.g. foreign-key).
RefName string // ref name; inverse only.
Ref *Descriptor // edge reference; to/from of the same type.
Through *struct{ N, T string } // through type and name.
Unique bool // unique edge.
Inverse bool // inverse edge.
Required bool // required on creation.
Immutable bool // create only edge.
StorageKey *StorageKey // optional storage-key configuration.
Annotations []schema.Annotation // edge annotations.
Comment string // edge comment.
Err error // error during descriptor construction.
}
A Descriptor for edge configuration.
type StorageKey ¶
type StorageKey struct {
Table string // Table or label.
Symbols []string // Symbols/names of the foreign-key constraints.
Columns []string // Foreign-key columns.
}
StorageKey holds the configuration for edge storage-key.
type StorageOption ¶
type StorageOption func(*StorageKey)
StorageOption allows for setting the storage configuration using functional options.
func Column ¶
func Column(name string) StorageOption
Column sets the foreign-key column name option for O2O, O2M and M2O edges. Note that, for M2M edges (2 columns), use the edge.Columns option.
func Columns ¶
func Columns(to, from string) StorageOption
Columns sets the foreign-key column names option for M2M edges. The 1st column defines the name of the "To" edge, and the 2nd defines the name of the "From" edge (inverse edge). Note that, for O2O, O2M and M2O edges, use the edge.Column option.
func Symbol ¶
func Symbol(symbol string) StorageOption
Symbol sets the symbol/name of the foreign-key constraint for O2O, O2M and M2O edges. Note that, for M2M edges (2 columns and 2 constraints), use the edge.Symbols option.
func Symbols ¶
func Symbols(to, from string) StorageOption
Symbols sets the symbol/name of the foreign-key constraints for M2M edges. The 1st column defines the name of the "To" edge, and the 2nd defines the name of the "From" edge (inverse edge). Note that, for O2O, O2M and M2O edges, use the edge.Symbol option.
Source Files