orm

Documentation

Index

• type Association
• type DispatchesEvents
• type Event
• type EventType
• type Factory
• type ModelToObserver
• type ModelWithConnection
• type ModelWithGlobalScopes
• type Observer
• type ObserverWithCreating
• type ObserverWithDeleting
• type ObserverWithForceDeleting
• type ObserverWithRestored
• type ObserverWithRestoring
• type ObserverWithRetrieved
• type ObserverWithSaved
• type ObserverWithSaving
• type ObserverWithUpdating
• type Orm
• type Query
• type QueryWithContext
• type QueryWithObserver
• type ToSql

Types

type Association

type Association interface {
	// Find finds records that match given conditions.
	Find(out any, conds ...any) error
	// Append appending a model to the association.
	Append(values ...any) error
	// Replace replaces the association with the given value.
	Replace(values ...any) error
	// Delete deletes the given value from the association.
	Delete(values ...any) error
	// Clear clears the association.
	Clear() error
	// Count returns the number of records in the association.
	Count() int64
}

type DispatchesEvents

type DispatchesEvents interface {
	// DispatchesEvents returns the event handlers.
	DispatchesEvents() map[EventType]func(Event) error
}

type Event

type Event interface {
	// Context returns the event context.
	Context() context.Context
	// GetAttribute returns the attribute value for the given key.
	GetAttribute(key string) any
	// GetOriginal returns the original attribute value for the given key.
	GetOriginal(key string, def ...any) any
	// IsClean returns true if the given column is clean.
	IsClean(columns ...string) bool
	// IsDirty returns true if the given column is dirty.
	IsDirty(columns ...string) bool
	// Query returns the query instance.
	Query() Query
	// SetAttribute sets the attribute value for the given key.
	SetAttribute(key string, value any)
}

type EventType

type EventType string

const (
	// Create events
	EventCreating EventType = "creating"
	EventCreated  EventType = "created"

	// Update events
	EventUpdating EventType = "updating"
	EventUpdated  EventType = "updated"

	// Save events
	EventSaving EventType = "saving"
	EventSaved  EventType = "saved"

	// Delete events
	EventDeleting      EventType = "deleting"
	EventDeleted       EventType = "deleted"
	EventForceDeleting EventType = "force_deleting"
	EventForceDeleted  EventType = "force_deleted"

	// Restore events
	EventRestoring EventType = "restoring"
	EventRestored  EventType = "restored"

	// Retrieve events
	EventRetrieved EventType = "retrieved"
)

type Factory

type Factory interface {
	// Count sets the number of models that should be generated.
	Count(count int) Factory
	// Create creates a model and persists it to the database.
	Create(value any, attributes ...map[string]any) error
	// CreateQuietly creates a model and persists it to the database without firing any model events.
	CreateQuietly(value any, attributes ...map[string]any) error
	// Make creates a model and returns it, but does not persist it to the database.
	Make(value any, attributes ...map[string]any) error
}

type ModelToObserver

type ModelToObserver struct {
	Model    any
	Observer Observer
}

type ModelWithConnection

type ModelWithConnection interface {
	// Connection gets the connection name for the model.
	Connection() string
}

type ModelWithGlobalScopes

type ModelWithGlobalScopes interface {
	GlobalScopes() []func(Query) Query
}

type Observer

type Observer interface {
	// Created called when the model has been created.
	Created(Event) error
	// Updated called when the model has been updated.
	Updated(Event) error
	// Deleted called when the model has been deleted.
	Deleted(Event) error
	// ForceDeleted called when the model has been force deleted.
	ForceDeleted(Event) error
}

type ObserverWithCreating

type ObserverWithCreating interface {
	// Creating called when the model is being created.
	Creating(Event) error
}

type ObserverWithDeleting

type ObserverWithDeleting interface {
	// Deleting called when the model is being deleted.
	Deleting(Event) error
}

type ObserverWithForceDeleting

type ObserverWithForceDeleting interface {
	// ForceDeleting called when the model is being force deleted.
	ForceDeleting(Event) error
}

type ObserverWithRestored

type ObserverWithRestored interface {
	// Restored called when the model has been restored.
	Restored(Event) error
}

type ObserverWithRestoring

type ObserverWithRestoring interface {
	// Restoring called when the model is being restored.
	Restoring(Event) error
}

type ObserverWithRetrieved

type ObserverWithRetrieved interface {
	// Retrieved called when the model is retrieved from the database.
	Retrieved(Event) error
}

type ObserverWithSaved

type ObserverWithSaved interface {
	// Saved called when the model has been saved.
	Saved(Event) error
}

type ObserverWithSaving

type ObserverWithSaving interface {
	// Saving called when the model is being saved.
	Saving(Event) error
}

type ObserverWithUpdating

type ObserverWithUpdating interface {
	// Updating called when the model is being updated.
	Updating(Event) error
}

type Orm

type Orm interface {
	// Config gets the database config.
	Config() database.Config
	// Connection gets an Orm instance from the connection pool.
	Connection(name string) Orm
	// DB gets the underlying database connection.
	DB() (*sql.DB, error)
	// Factory gets a new factory instance for the given model name.
	Factory() Factory
	// DatabaseName gets the current database name.
	DatabaseName() string
	// Name gets the current connection name.
	Name() string
	// Observe registers an observer with the Orm.
	Observe(model any, observer Observer)
	// Query gets a new query builder instance.
	Query() Query
	// Fresh resets the Orm instance.
	Fresh()
	// SetQuery sets the query builder instance.
	SetQuery(query Query)
	// Transaction runs a callback wrapped in a database transaction.
	Transaction(txFunc func(tx Query) error) error
	// WithContext sets the context to be used by the Orm.
	WithContext(ctx context.Context) Orm
}

type Query

type Query interface {
	// Association gets an association instance by name.
	Association(association string) Association
	// Begin begins a new transaction
	// DEPRECATED Use BeginTransaction instead.
	Begin() (Query, error)
	// BeginTransaction begins a new transaction
	BeginTransaction() (Query, error)
	// Commit commits the changes in a transaction.
	Commit() error
	// Count retrieve the "count" result of the query.
	Count() (int64, error)
	// Create inserts new record into the database.
	Create(value any) error
	// Cursor returns a cursor, use scan to iterate over the returned rows.
	Cursor() chan db.Row
	// DB gets the underlying database connection.
	DB() (*sql.DB, error)
	// Delete deletes records matching given conditions, if the conditions are empty will delete all records.
	Delete(value ...any) (*db.Result, error)
	// Distinct specifies distinct fields to query.
	Distinct(columns ...string) Query
	// Driver gets the driver for the query.
	Driver() string
	// Exec executes raw sql
	Exec(sql string, values ...any) (*db.Result, error)
	// Exists returns true if matching records exist; otherwise, it returns false.
	Exists() (bool, error)
	// Find finds records that match given conditions.
	Find(dest any, conds ...any) error
	// FindOrFail finds records that match given conditions or throws an error.
	FindOrFail(dest any, conds ...any) error
	// First finds record that match given conditions.
	First(dest any) error
	// FirstOr finds the first record that matches the given conditions or
	// execute the callback and return its result if no record is found.
	FirstOr(dest any, callback func() error) error
	// FirstOrCreate finds the first record that matches the given attributes
	// or create a new one with those attributes if none was found.
	FirstOrCreate(dest any, conds ...any) error
	// FirstOrFail finds the first record that matches the given conditions or throws an error.
	FirstOrFail(dest any) error
	// FirstOrNew finds the first record that matches the given conditions or
	// return a new instance of the model initialized with those attributes.
	FirstOrNew(dest any, attributes any, values ...any) error
	// ForceDelete forces delete records matching given conditions.
	ForceDelete(value ...any) (*db.Result, error)
	// Get retrieves all rows from the database.
	Get(dest any) error
	// Group specifies the group method on the query.
	// DEPRECATED Use GroupBy instead.
	Group(column string) Query
	// GroupBy specifies the group method on the query.
	GroupBy(column ...string) Query
	// Having specifying HAVING conditions for the query.
	Having(query any, args ...any) Query
	// InRandomOrder specifies the order randomly.
	InRandomOrder() Query
	// InTransaction checks if the query is in a transaction.
	InTransaction() bool
	// Join specifying JOIN conditions for the query.
	Join(query string, args ...any) Query
	// Limit the number of records returned.
	Limit(limit int) Query
	// Load loads a relationship for the model.
	Load(dest any, relation string, args ...any) error
	// LoadMissing loads a relationship for the model that is not already loaded.
	LoadMissing(dest any, relation string, args ...any) error
	// LockForUpdate locks the selected rows in the table for updating.
	LockForUpdate() Query
	// Model sets the model instance to be queried.
	Model(value any) Query
	// Offset specifies the number of records to skip before starting to return the records.
	Offset(offset int) Query
	// Omit specifies columns that should be omitted from the query.
	Omit(columns ...string) Query
	// Order specifies the order in which the results should be returned.
	// DEPRECATED Use OrderByRaw instead.
	Order(value any) Query
	// OrderBy specifies the order should be ascending.
	OrderBy(column string, direction ...string) Query
	// OrderByDesc specifies the order should be descending.
	OrderByDesc(column string) Query
	// OrderByRaw specifies the order should be raw.
	OrderByRaw(raw string) Query
	// OrWhere add an "or where" clause to the query.
	OrWhere(query any, args ...any) Query
	// OrWhereBetween adds an "or where column between x and y" clause to the query.
	OrWhereBetween(column string, x, y any) Query
	// OrWhereIn adds an "or where column in" clause to the query.
	OrWhereIn(column string, values []any) Query
	// OrWhereJsonContains adds an "or where JSON contains" clause to the query.
	OrWhereJsonContains(column string, value any) Query
	// OrWhereJsonContainsKey add a clause that determines if a JSON path exists to the query.
	OrWhereJsonContainsKey(column string) Query
	// OrWhereJsonDoesntContain add an "or where JSON not contains" clause to the query.
	OrWhereJsonDoesntContain(column string, value any) Query
	// OrWhereJsonDoesntContainKey add a clause that determines if a JSON path does not exist to the query.
	OrWhereJsonDoesntContainKey(column string) Query
	// OrWhereJsonLength add an "or where JSON length" clause to the query.
	OrWhereJsonLength(column string, length int) Query
	// OrWhereNotBetween adds an "or where column not between x and y" clause to the query.
	OrWhereNotBetween(column string, x, y any) Query
	// OrWhereNotIn adds an "or where column not in" clause to the query.
	OrWhereNotIn(column string, values []any) Query
	// OrWhereNull adds a "or where column is null" clause to the query.
	OrWhereNull(column string) Query
	// Paginate the given query into a simple paginator.
	Paginate(page, limit int, dest any, total *int64) error
	// Pluck retrieves a single column from the database.
	Pluck(column string, dest any) error
	// Raw creates a raw query.
	Raw(sql string, values ...any) Query
	// Restore restores a soft deleted model.
	Restore(model ...any) (*db.Result, error)
	// Rollback rolls back the changes in a transaction.
	Rollback() error
	// Save updates value in a database
	Save(value any) error
	// SaveQuietly updates value in a database without firing events
	SaveQuietly(value any) error
	// Scan scans the query result and populates the destination object.
	Scan(dest any) error
	// Scopes applies one or more query scopes.
	Scopes(funcs ...func(Query) Query) Query
	// Select specifies fields that should be retrieved from the database.
	Select(columns ...string) Query
	// SelectRaw specifies a raw SQL query for selecting fields.
	SelectRaw(query any, args ...any) Query
	// SharedLock locks the selected rows in the table.
	SharedLock() Query
	// Sum calculates the sum of a column's values and populates the destination object.
	Sum(column string) (int64, error)
	// Table specifies the table for the query.
	Table(name string, args ...any) Query
	// ToSql returns the query as a SQL string.
	ToSql() ToSql
	// ToRawSql returns the query as a raw SQL string.
	ToRawSql() ToSql
	// Update updates records with the given column and values
	Update(column any, value ...any) (*db.Result, error)
	// UpdateOrCreate finds the first record that matches the given attributes
	// or create a new one with those attributes if none was found.
	UpdateOrCreate(dest any, attributes any, values any) error
	// Where add a "where" clause to the query.
	Where(query any, args ...any) Query
	// WhereBetween adds a "where column between x and y" clause to the query.
	WhereBetween(column string, x, y any) Query
	// WhereIn adds a "where column in" clause to the query.
	WhereIn(column string, values []any) Query
	// WhereJsonContains add a "where JSON contains" clause to the query.
	WhereJsonContains(column string, value any) Query
	// WhereJsonContainsKey add a clause that determines if a JSON path exists to the query.
	WhereJsonContainsKey(column string) Query
	// WhereJsonDoesntContain add a "where JSON not contains" clause to the query.
	WhereJsonDoesntContain(column string, value any) Query
	// WhereJsonDoesntContainKey add a clause that determines if a JSON path does not exist to the query.
	WhereJsonDoesntContainKey(column string) Query
	// WhereJsonLength add a "where JSON length" clause to the query.
	WhereJsonLength(column string, length int) Query
	// WhereNotBetween adds a "where column not between x and y" clause to the query.
	WhereNotBetween(column string, x, y any) Query
	// WhereNotIn adds a "where column not in" clause to the query.
	WhereNotIn(column string, values []any) Query
	// WhereNotNull adds a "where column is not null" clause to the query.
	WhereNotNull(column string) Query
	// WhereNull adds a "where column is null" clause to the query.
	WhereNull(column string) Query
	// WithoutEvents disables event firing for the query.
	WithoutEvents() Query
	// WithTrashed allows soft deleted models to be included in the results.
	WithTrashed() Query
	// With returns a new query instance with the given relationships eager loaded.
	With(query string, args ...any) Query
}

type QueryWithContext

type QueryWithContext interface {
	WithContext(ctx context.Context) Query
}

type QueryWithObserver

type QueryWithObserver interface {
	Observe(model any, observer Observer)
}

type ToSql

type ToSql interface {
	Count() string
	Create(value any) string
	Delete(value ...any) string
	Find(dest any, conds ...any) string
	First(dest any) string
	ForceDelete(value ...any) string
	Get(dest any) string
	Pluck(column string, dest any) string
	Save(value any) string
	Sum(column string, dest any) string
	Update(column any, value ...any) string
}