Documentation
¶
Overview ¶
Package orm provides an ActiveRecord-style Model, a fluent query builder, hooks, casts, soft-deletes, 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 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
- type AfterCreateHook
- type AfterDeleteHook
- type AfterFindHook
- type AfterSaveHook
- type AfterUpdateHook
- type BeforeCreateHook
- type BeforeDeleteHook
- type BeforeSaveHook
- type BeforeUpdateHook
- type Builder
- 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]) 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]) QB() *query.Builder
- 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 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 deletes the model — soft-delete when the schema supports it, hard delete otherwise.
func ForceDelete ¶
ForceDelete bypasses soft-delete and removes the 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]) OnlyTrashed ¶
OnlyTrashed restricts to soft-deleted rows.
func (*Builder[T]) WhereNotNull ¶
WhereNotNull appends IS NOT NULL.
func (*Builder[T]) WithTrashed ¶
WithTrashed includes soft-deleted rows in the result.
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"`
DeletedAt sql.NullTime `column:"deleted_at" orm:"nullable"`
}
Model is the base struct most models embed. It provides the standard id/created_at/updated_at/deleted_at columns. Models that do not need soft deletes can embed Timestamps instead.
Source Files