Documentation
¶
Overview ¶
Package orm provides an ActiveRecord-style Model, a fluent query builder, hooks, casts, and relationships. Models are plain Go structs that embed orm.Model (or one of the timestamp variants) and live without a global router — the only required dependency is a *database.Connection.
Example:
type User struct {
orm.Model
Name string
Email string `orm:"unique"`
}
user := &User{Name: "Ada", Email: "ada@example.com"}
if err := orm.Save(ctx, conn, user); err != nil { ... }
var users []User
err := orm.Query[User](conn).Where("email", "like", "%@example.com").Get(ctx, &users)
Index ¶
- Variables
- func Delete[T any](ctx context.Context, conn *database.Connection, model *T) error
- func FirstOrCreate[T any](ctx context.Context, conn *database.Connection, where map[string]any, ...) (*T, error)
- func ForceDelete[T any](ctx context.Context, conn *database.Connection, model *T) error
- func Pluck[T any, V any](ctx context.Context, b *Builder[T], col string) ([]V, error)
- func Restore[T any](ctx context.Context, conn *database.Connection, model *T) error
- func Save[T any](ctx context.Context, conn *database.Connection, model *T) error
- func UpdateOrCreate[T any](ctx context.Context, conn *database.Connection, where map[string]any, ...) (*T, error)
- type AfterCreateHook
- type AfterDeleteHook
- type AfterFindHook
- type AfterSaveHook
- type AfterUpdateHook
- type BeforeCreateHook
- type BeforeDeleteHook
- type BeforeSaveHook
- type BeforeUpdateHook
- type Builder
- func (b *Builder[T]) Chunk(ctx context.Context, size int, fn func([]T) error) error
- func (b *Builder[T]) Count(ctx context.Context) (int64, error)
- func (b *Builder[T]) Exists(ctx context.Context) (bool, error)
- func (b *Builder[T]) Find(ctx context.Context, id any) (*T, error)
- func (b *Builder[T]) First(ctx context.Context) (*T, error)
- func (b *Builder[T]) FirstOrFail(ctx context.Context) (*T, error)
- func (b *Builder[T]) Get(ctx context.Context, dst *[]T) error
- func (b *Builder[T]) Limit(n int) *Builder[T]
- func (b *Builder[T]) Offset(n int) *Builder[T]
- func (b *Builder[T]) OnlyTrashed() *Builder[T]
- func (b *Builder[T]) OrWhere(args ...any) *Builder[T]
- func (b *Builder[T]) OrderBy(col, dir string) *Builder[T]
- func (b *Builder[T]) Paginate(ctx context.Context, page, perPage int) (*Paginator[T], error)
- func (b *Builder[T]) QB() *query.Builder
- func (b *Builder[T]) Scope(fn func(*Builder[T]) *Builder[T]) *Builder[T]
- func (b *Builder[T]) Where(args ...any) *Builder[T]
- func (b *Builder[T]) WhereIn(col string, values any) *Builder[T]
- func (b *Builder[T]) WhereNotNull(col string) *Builder[T]
- func (b *Builder[T]) WhereNull(col string) *Builder[T]
- func (b *Builder[T]) WithTrashed() *Builder[T]
- func (b *Builder[T]) WithTx(tx *database.Tx) *Builder[T]
- type Connectioner
- type Fillable
- type Hidden
- type HookContext
- type Model
- type Paginator
- type SoftDeletes
- type Tabler
- type Timestamps
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("orm: record not found")
ErrNotFound is returned by First/FirstOrFail when no row matches.
Functions ¶
func Delete ¶
Delete removes the model's row from the database. For soft-deletable models (those carrying a deleted_at column) it issues an UPDATE that stamps deleted_at instead of a real DELETE; use ForceDelete for an unconditional removal.
func FirstOrCreate ¶ added in v0.21.0
func FirstOrCreate[T any](ctx context.Context, conn *database.Connection, where map[string]any, defaults ...map[string]any) (*T, error)
FirstOrCreate returns the first row matching where, or inserts a new row merging where and the optional defaults (defaults override where on key collisions). The returned model reflects the persisted row, including a generated primary key on the create path.
func ForceDelete ¶
ForceDelete permanently removes the model's row, bypassing soft deletes.
func Restore ¶
Restore clears the deleted_at column of a soft-deleted model, bringing the row back into the default query scope. It is an error to call Restore on a model that is not soft-deletable.
func Save ¶
Save persists a model: it inserts when the primary key is zero, otherwise updates. Hooks are dispatched around the operation. Timestamps are set automatically.
func UpdateOrCreate ¶ added in v0.21.0
func UpdateOrCreate[T any](ctx context.Context, conn *database.Connection, where map[string]any, values map[string]any) (*T, error)
UpdateOrCreate updates the first row matching where with values, or inserts a new row merging where and values when no match exists. The returned model reflects the persisted row.
Types ¶
type AfterCreateHook ¶
type AfterCreateHook interface{ AfterCreate(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type AfterDeleteHook ¶
type AfterDeleteHook interface{ AfterDelete(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type AfterFindHook ¶
type AfterFindHook interface{ AfterFind(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type AfterSaveHook ¶
type AfterSaveHook interface{ AfterSave(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type AfterUpdateHook ¶
type AfterUpdateHook interface{ AfterUpdate(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type BeforeCreateHook ¶
type BeforeCreateHook interface{ BeforeCreate(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type BeforeDeleteHook ¶
type BeforeDeleteHook interface{ BeforeDelete(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type BeforeSaveHook ¶
type BeforeSaveHook interface{ BeforeSave(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type BeforeUpdateHook ¶
type BeforeUpdateHook interface{ BeforeUpdate(*HookContext) error }
BeforeCreate / AfterCreate / etc. are optional hook interfaces.
type Builder ¶
type Builder[T any] struct { // contains filtered or unexported fields }
Builder is a model-aware wrapper around query.Builder.
func Query ¶
func Query[T any](conn *database.Connection) *Builder[T]
Query returns a fresh model builder.
func (*Builder[T]) Chunk ¶ added in v0.21.0
Chunk iterates the result set in batches of size, invoking fn for each non-empty batch. It paginates by ascending primary key (a keyset cursor) so the whole set is never loaded into memory at once. Returning a non-nil error from fn stops the iteration and propagates the error. size is clamped to a minimum of 1.
func (*Builder[T]) Exists ¶
Exists reports whether any matching row exists (honoring the soft-delete scope).
func (*Builder[T]) Find ¶
Find by primary key. It clones the underlying builder so repeated Find calls on the same receiver (Find(id1) then Find(id2)) do not accumulate WHERE clauses.
func (*Builder[T]) First ¶
First returns the first matching row, or ErrNotFound. It runs against a clone of the underlying builder so the receiver keeps its full clause state and can still be used for Get/Count afterwards.
func (*Builder[T]) FirstOrFail ¶ added in v0.20.0
FirstOrFail is an alias for First: it returns the first matching row or ErrNotFound. Provided for call-site readability when the absence of a row is an error condition.
func (*Builder[T]) OnlyTrashed ¶
OnlyTrashed restricts the results to soft-deleted rows only. No-op on models that are not soft-deletable.
func (*Builder[T]) Paginate ¶ added in v0.21.0
Paginate runs a COUNT (respecting the current WHERE and soft-delete scope) followed by a LIMIT/OFFSET query, returning the requested page. page and perPage are clamped to a minimum of 1.
func (*Builder[T]) Scope ¶ added in v0.21.0
Scope applies a reusable constraint to the builder and returns it, so common query fragments can be factored into a named function:
active := func(q *orm.Builder[User]) *orm.Builder[User] { return q.Where("active", true) }
orm.Query[User](conn).Scope(active).Get(ctx, &users)
func (*Builder[T]) WhereNotNull ¶
WhereNotNull appends IS NOT NULL.
func (*Builder[T]) WithTrashed ¶
WithTrashed includes soft-deleted rows in the results. No-op on models that are not soft-deletable.
type Connectioner ¶
type Connectioner interface {
ConnectionName() string
}
Connectioner may be implemented on a model to pin it to a specific named connection from the database.Manager. Useful in multi-tenant or multi-database setups.
type Fillable ¶
type Fillable interface {
FillableColumns() []string
}
Fillable may be implemented to whitelist columns for mass assignment.
type Hidden ¶
type Hidden interface {
HiddenColumns() []string
}
Hidden may be implemented to hide columns from ToMap serialization.
type HookContext ¶
HookContext is passed to lifecycle hooks. It exposes the active transaction-or-connection executor and the underlying context.Context.
func (*HookContext) Executor ¶
func (h *HookContext) Executor() database.Executor
Executor returns the active executor, preferring the transaction if open.
type Model ¶
type Model struct {
ID uint64 `column:"id" orm:"primary;autoincrement"`
CreatedAt time.Time `column:"created_at"`
UpdatedAt time.Time `column:"updated_at"`
}
Model is the base struct most models embed. It provides the standard id/created_at/updated_at columns.
type Paginator ¶ added in v0.21.0
type Paginator[T any] struct { Data []T `json:"data"` Total int64 `json:"total"` Page int `json:"page"` PerPage int `json:"per_page"` LastPage int `json:"last_page"` HasMore bool `json:"has_more"` }
Paginator is the result of Builder.Paginate. Data holds the current page's rows; the remaining fields describe the position within the full result set.
type SoftDeletes ¶ added in v0.21.0
type SoftDeletes struct {
ID uint64 `column:"id" orm:"primary;autoincrement"`
CreatedAt time.Time `column:"created_at"`
UpdatedAt time.Time `column:"updated_at"`
DeletedAt *time.Time `column:"deleted_at"`
}
SoftDeletes is a base struct that adds a nullable deleted_at column on top of the standard id/created_at/updated_at columns. A model embedding it becomes "soft-deletable": orm.Delete sets deleted_at instead of issuing a real DELETE, and query builders exclude soft-deleted rows by default. Use orm.ForceDelete for a real delete and orm.Restore to bring a row back.
Source Files