orm

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package orm provides the runtime ORM for querying and mutating application models.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = dormerrors.ErrNotFound

Functions

This section is empty.

Types

type AccessPolicyEvent added in v0.4.0 

type AccessPolicyEvent struct {
	Kind        AccessPolicyEventKind
	Field       string
	SQL         string
	Arguments   []any
	Policy      string
	Description string
}

AccessPolicyEvent describes a security-related policy action.

type AccessPolicyEventKind added in v0.4.0 

type AccessPolicyEventKind string

AccessPolicyEventKind classifies an access-policy action in the execution report. 

const (
	AccessPolicyEventInjectedPredicate AccessPolicyEventKind = "injected_predicate"
	AccessPolicyEventInjectedField     AccessPolicyEventKind = "injected_field"
	AccessPolicyEventInheritedPolicy   AccessPolicyEventKind = "inherited_policy"
	AccessPolicyEventPolicyOverride    AccessPolicyEventKind = "policy_override"
	AccessPolicyEventSoftDelete        AccessPolicyEventKind = "soft_delete"
)

type AfterCreateHook added in v0.1.1 

type AfterCreateHook interface {
	AfterCreate(context.Context, *DB) error
}

type AfterDeleteHook added in v0.1.1 

type AfterDeleteHook interface {
	AfterDelete(context.Context, *DB) error
}

type AfterFindHook added in v0.1.1 

type AfterFindHook interface {
	AfterFind(context.Context, *DB) error
}

type AfterUpdateHook added in v0.1.1 

type AfterUpdateHook interface {
	AfterUpdate(context.Context, *DB) error
}

type Attribute 

type Attribute struct {
	Key   string
	Value any
}

Attribute is a key-value pair attached to spans and metrics.

type AuditAction added in v0.4.0 

type AuditAction struct {
	Field       string
	Value       any
	Kind        string
	Description string
}

AuditAction describes an automatic audit field assignment.

type BeforeCreateHook added in v0.1.1 

type BeforeCreateHook interface {
	BeforeCreate(context.Context, *DB) error
}

type BeforeDeleteHook added in v0.1.1 

type BeforeDeleteHook interface {
	BeforeDelete(context.Context, *DB) error
}

type BeforeFindHook added in v0.1.1 

type BeforeFindHook interface {
	BeforeFind(context.Context) error
}

type BeforeUpdateHook added in v0.1.1 

type BeforeUpdateHook interface {
	BeforeUpdate(context.Context, *DB) error
}

type Config 

type Config struct {
	DB                  *sql.DB
	Tx                  *sql.Tx
	Context             context.Context
	Dialect             dialect.Dialect
	DriverName          string
	Schema              *schema.Schema
	Logger              Logger
	Observability       ObservabilityConfig
	Access              access.Engine
	QueryAdvisor        QueryAdvisor
	PrepareStatements   bool
	SoftDeleteByDefault bool
	BatchSize           int
}

type Counter 

type Counter interface {
	Add(context.Context, float64, ...Attribute)
}

Counter records monotonic values.

type DB 

type DB struct {
	// contains filtered or unexported fields
}

func New 

func New(cfg Config) *DB

func (*DB) Begin added in v0.3.0 

func (db *DB) Begin(ctx context.Context) (*DB, error)

func (*DB) Close added in v0.1.1 

func (db *DB) Close() error

func (*DB) Commit added in v0.3.0 

func (db *DB) Commit() error

func (*DB) Count added in v0.3.0 

func (db *DB) Count(model any, opts ...QueryOption) (int64, error)

func (*DB) Create added in v0.3.0 

func (db *DB) Create(model any) error

func (*DB) CreateMany added in v0.3.1 

func (db *DB) CreateMany(ctx context.Context, models any) error

func (*DB) Delete added in v0.3.0 

func (db *DB) Delete(model any) error

func (*DB) DeleteMany added in v0.3.1 

func (db *DB) DeleteMany(ctx context.Context, models any) error

func (*DB) Dialect added in v0.1.1 

func (db *DB) Dialect() dialect.Dialect

func (*DB) DriverName added in v0.4.4 

func (db *DB) DriverName() string

DriverName returns the configured driver name.

func (*DB) DryRun added in v0.4.0 

func (db *DB) DryRun() *DryRunSession

func (*DB) Exists added in v0.4.4 

func (db *DB) Exists(model any, opts ...QueryOption) (bool, error)

func (*DB) Find added in v0.3.0 

func (db *DB) Find(dest any, opts ...QueryOption) error

func (*DB) FindOne added in v0.3.0 

func (db *DB) FindOne(dest any, opts ...QueryOption) error

func (*DB) Observability added in v0.4.4 

func (db *DB) Observability() ObservabilityConfig

Observability returns the current observability configuration.

func (*DB) Ping added in v0.1.1 

func (db *DB) Ping(ctx context.Context) error

func (*DB) PingContext added in v0.1.1 

func (db *DB) PingContext(ctx context.Context) error

func (*DB) Raw added in v0.3.2 

func (db *DB) Raw(ctx context.Context, query string, args ...any) *RawBuilder

Raw creates a Raw SQL builder from a DB handle.

func (*DB) Rollback added in v0.3.0 

func (db *DB) Rollback() error

func (*DB) SQLDB added in v0.1.1 

func (db *DB) SQLDB() *sql.DB

func (*DB) SoftDelete added in v0.3.0 

func (db *DB) SoftDelete(model any) error

func (*DB) Stats added in v0.1.1 

func (db *DB) Stats() sql.DBStats

func (*DB) Transaction added in v0.3.0 

func (db *DB) Transaction(ctx context.Context, fn func(*DB) error) error

func (*DB) Tx 

func (db *DB) Tx(ctx context.Context, fn func(*Session) error) error

func (*DB) Update added in v0.3.0 

func (db *DB) Update(model any) error

func (*DB) UpdateMany added in v0.3.1 

func (db *DB) UpdateMany(ctx context.Context, models any) error

func (*DB) UpdateWhere added in v0.3.0 

func (db *DB) UpdateWhere(model any, opts ...QueryOption) error

func (*DB) Upsert added in v0.3.0 

func (db *DB) Upsert(model any) error

func (*DB) WithContext 

func (db *DB) WithContext(ctx context.Context) *Session

func (*DB) WithPolicy added in v0.1.1 

func (db *DB) WithPolicy(policy access.Policy) *Session

type DryRunSession added in v0.4.0 

type DryRunSession struct {
	// contains filtered or unexported fields
}

func (*DryRunSession) Count added in v0.4.0 

func (d *DryRunSession) Count(ctx context.Context, model any, opts ...QueryOption) (ExecutionReport, int64, error)

func (*DryRunSession) Create added in v0.4.0 

func (d *DryRunSession) Create(ctx context.Context, model any) (ExecutionReport, error)

func (*DryRunSession) Delete added in v0.4.0 

func (d *DryRunSession) Delete(ctx context.Context, model any) (ExecutionReport, error)

func (*DryRunSession) Find added in v0.4.0 

func (d *DryRunSession) Find(ctx context.Context, dest any, opts ...QueryOption) (ExecutionReport, error)

func (*DryRunSession) FindOne added in v0.4.0 

func (d *DryRunSession) FindOne(ctx context.Context, dest any, opts ...QueryOption) (ExecutionReport, error)

func (*DryRunSession) SoftDelete added in v0.4.0 

func (d *DryRunSession) SoftDelete(ctx context.Context, model any) (ExecutionReport, error)

func (*DryRunSession) Update added in v0.4.0 

func (d *DryRunSession) Update(ctx context.Context, model any) (ExecutionReport, error)

func (*DryRunSession) UpdateWhere added in v0.4.0 

func (d *DryRunSession) UpdateWhere(ctx context.Context, model any, opts ...QueryOption) (ExecutionReport, error)

func (*DryRunSession) Upsert added in v0.4.0 

func (d *DryRunSession) Upsert(ctx context.Context, model any) (ExecutionReport, error)

type ExecutionReport added in v0.4.0 

type ExecutionReport struct {
	Version           int
	Operation         string
	Table             string
	SQL               string
	Parameters        []any
	Statements        []ExecutionStatement
	AccessPolicies    []AccessPolicyEvent
	AuditActions      []AuditAction
	LifecycleHooks    []LifecycleHookEvent
	QueryAdvisor      []QueryAdvisorFinding
	OptimisticLocking *OptimisticLockingInfo
	ExecutionStatus   ExecutionStatus
	Metadata          map[string]any
}

ExecutionReport captures the observable behavior of an ORM operation.

type ExecutionStatement added in v0.4.0 

type ExecutionStatement struct {
	Operation  string
	SQL        string
	Parameters []any
}

ExecutionStatement captures a single generated SQL statement.

type ExecutionStatus added in v0.4.0 

type ExecutionStatus string

ExecutionStatus describes what happened at the terminal execution step. 

const (
	// ExecutionStatusSkipped indicates that SQL execution was intentionally skipped.
	ExecutionStatusSkipped ExecutionStatus = "Skipped"
)

type Histogram 

type Histogram interface {
	Record(context.Context, float64, ...Attribute)
}

Histogram records duration or size distributions.

type LifecycleHookEvent added in v0.4.0 

type LifecycleHookEvent struct {
	Order int
	Name  string
	Model string
}

LifecycleHookEvent describes a lifecycle hook invocation.

type Logger 

type Logger interface {
	Printf(string, ...any)
}

type Meter 

type Meter interface {
	Counter(name string) Counter
	Histogram(name string) Histogram
}

Meter creates counters and histograms.

type MeterProvider 

type MeterProvider interface {
	Meter(name string) Meter
}

MeterProvider creates named meters.

type Observability added in v0.1.10 

type Observability = ObservabilityConfig

Observability is an alias kept for the public API documented in ADR-026.

type ObservabilityConfig 

type ObservabilityConfig struct {
	Tracing            bool
	Metrics            bool
	TraceSQL           TraceSQLMode
	SQLLogging         SQLLogMode
	SlowQueryThreshold time.Duration
	MaskParameters     bool
	MaskedFields       []string
	Logger             ObservabilityLogger
	TracerProvider     TracerProvider
	MeterProvider      MeterProvider
}

ObservabilityConfig configures tracing, metrics, and SQL visibility.

func DefaultObservabilityConfig 

func DefaultObservabilityConfig() ObservabilityConfig

DefaultObservabilityConfig returns the default observability configuration.

func (ObservabilityConfig) Enabled 

func (c ObservabilityConfig) Enabled() bool

Enabled reports whether any observability feature is active.

func (ObservabilityConfig) Normalized 

func (c ObservabilityConfig) Normalized() ObservabilityConfig

Normalized returns a copy with defaults applied.

func (ObservabilityConfig) ShouldMask 

func (c ObservabilityConfig) ShouldMask(field string) bool

ShouldMask reports whether a field name should be redacted in logs.

func (ObservabilityConfig) Validate 

func (c ObservabilityConfig) Validate() error

Validate checks that the configuration is internally consistent.

type ObservabilityLogger 

type ObservabilityLogger interface {
	LogSQL(context.Context, SQLLogEntry)
	LogError(context.Context, error)
}

ObservabilityLogger receives SQL logs and error events.

type OptimisticLockingInfo added in v0.4.1 

type OptimisticLockingInfo struct {
	Enabled  bool
	Column   string
	Current  any
	Next     any
	Conflict bool
}

OptimisticLockingInfo describes optimistic-lock metadata for inspection and tracing.

type QueryAdvisor added in v0.4.0 

type QueryAdvisor interface {
	Inspect(context.Context, QueryAdvisorInput) (QueryAdvisorReport, error)
}

QueryAdvisor evaluates a generated statement and returns advisory findings.

type QueryAdvisorFinding added in v0.4.0 

type QueryAdvisorFinding struct {
	Code           string
	Rule           string
	Severity       string
	Title          string
	Details        string
	Recommendation string
	Table          string
	Columns        []string
}

QueryAdvisorFinding describes a recommendation from the query advisor.

type QueryAdvisorInput added in v0.4.0 

type QueryAdvisorInput struct {
	Operation string
	Table     string
	SQL       string
	Schema    *schema.Schema
}

QueryAdvisorInput describes a query advisor request.

type QueryAdvisorReport added in v0.4.0 

type QueryAdvisorReport struct {
	Table    string
	SQL      string
	Kind     string
	Findings []QueryAdvisorFinding
}

QueryAdvisorReport captures query advisor output in a neutral form.

type QueryOption 

type QueryOption func(*queryState)

func CrossJoin added in v0.4.4 

func CrossJoin(table string) QueryOption

func Distinct added in v0.4.4 

func Distinct() QueryOption

func GroupBy added in v0.4.4 

func GroupBy(expr string) QueryOption

func Having added in v0.4.4 

func Having(expr string, args ...any) QueryOption

func InnerJoin added in v0.4.4 

func InnerJoin(table, on string, args ...any) QueryOption

func LeftJoin added in v0.4.4 

func LeftJoin(table, on string, args ...any) QueryOption

func Limit 

func Limit(n int) QueryOption

func Offset 

func Offset(n int) QueryOption

func OrderBy 

func OrderBy(expr string) QueryOption

func RightJoin added in v0.4.4 

func RightJoin(table, on string, args ...any) QueryOption

func Select added in v0.4.4 

func Select(expr string) QueryOption

func Where 

func Where(expr string, args ...any) QueryOption

type RawBuilder added in v0.3.2 

type RawBuilder struct {
	// contains filtered or unexported fields
}

RawBuilder executes explicit SQL with an opt-in policy bypass.

func (*RawBuilder) Exec added in v0.3.2 

func (r *RawBuilder) Exec() (sql.Result, error)

Exec executes a Raw SQL statement and returns the driver result.

func (*RawBuilder) Scan added in v0.3.2 

func (r *RawBuilder) Scan(dest any) error

Scan executes a Raw SQL query and scans the result into a destination slice.

func (*RawBuilder) WithoutPolicy added in v0.3.2 

func (r *RawBuilder) WithoutPolicy() *RawBuilder

WithoutPolicy explicitly acknowledges that Raw SQL bypasses access policy.

type SQLLogEntry 

type SQLLogEntry struct {
	SQL          string
	Args         []any
	Duration     time.Duration
	AffectedRows int64
	Timestamp    time.Time
	Err          error
	Slow         bool
	Visibility   TraceSQLMode
	Driver       string
	Dialect      string
	Operation    string
	Table        string
}

SQLLogEntry captures a single SQL log event.

type SQLLogMode 

type SQLLogMode string

SQLLogMode controls how SQL statements are reported by the legacy logger path. 

const (
	SQLLogDisabled   SQLLogMode = "disabled"
	SQLLogErrorsOnly SQLLogMode = "errors_only"
	SQLLogSlow       SQLLogMode = "slow_queries"
	SQLLogDebug      SQLLogMode = "debug"
	SQLLogTrace      SQLLogMode = "trace"
)

type Session 

type Session struct {
	// contains filtered or unexported fields
}

func (*Session) Count added in v0.1.8 

func (s *Session) Count(model any, opts ...QueryOption) (int64, error)

Count returns the number of rows matching the model type and query options.

func (*Session) Create 

func (s *Session) Create(model any) error

func (*Session) CreateMany added in v0.3.1 

func (s *Session) CreateMany(models any) error

func (*Session) Delete 

func (s *Session) Delete(model any) error

func (*Session) DeleteMany added in v0.3.1 

func (s *Session) DeleteMany(models any) error

func (*Session) Dialect added in v0.4.4 

func (s *Session) Dialect() dialect.Dialect

Dialect returns the configured SQL dialect.

func (*Session) DriverName added in v0.4.4 

func (s *Session) DriverName() string

DriverName returns the configured driver name.

func (*Session) DryRun added in v0.4.0 

func (s *Session) DryRun() *DryRunSession

func (*Session) Exists added in v0.4.4 

func (s *Session) Exists(model any, opts ...QueryOption) (bool, error)

Exists reports whether any row matches the query options.

func (*Session) Find 

func (s *Session) Find(dest any, opts ...QueryOption) error

func (*Session) FindOne 

func (s *Session) FindOne(dest any, opts ...QueryOption) error

func (*Session) Load added in v0.1.1 

func (s *Session) Load(dest any, relation string) error

func (*Session) Observability added in v0.4.4 

func (s *Session) Observability() ObservabilityConfig

Observability returns the underlying database observability configuration.

func (*Session) Preload added in v0.1.1 

func (s *Session) Preload(dest any, relations ...string) error

func (*Session) Raw added in v0.3.2 

func (s *Session) Raw(ctx context.Context, query string, args ...any) *RawBuilder

Raw creates a Raw SQL builder from a session handle.

func (*Session) SoftDelete 

func (s *Session) SoftDelete(model any) error

func (*Session) Tx 

func (s *Session) Tx(fn func(*Session) error) error

func (*Session) Update 

func (s *Session) Update(model any) error

func (*Session) UpdateMany added in v0.3.1 

func (s *Session) UpdateMany(models any) error

func (*Session) UpdateWhere added in v0.1.9 

func (s *Session) UpdateWhere(model any, opts ...QueryOption) error

UpdateWhere updates rows matching explicit query filters.

func (*Session) Upsert 

func (s *Session) Upsert(model any) error

func (*Session) WithContext added in v0.1.1 

func (s *Session) WithContext(ctx context.Context) *Session

func (*Session) WithDeleted 

func (s *Session) WithDeleted() *Session

func (*Session) WithPolicy added in v0.1.1 

func (s *Session) WithPolicy(policy access.Policy) *Session

type Span 

type Span interface {
	End()
	RecordError(error)
	SetAttributes(...Attribute)
}

Span represents an active trace span.

type SpanOption 

type SpanOption interface {
	// contains filtered or unexported methods
}

SpanOption configures span creation.

type TraceSQLMode added in v0.1.10 

type TraceSQLMode string

TraceSQLMode controls how much SQL detail is exposed through traces. 

const (
	TraceSQLDisabled          TraceSQLMode = "disabled"
	TraceSQLMetadata          TraceSQLMode = "metadata"
	TraceSQLStatement         TraceSQLMode = "statement"
	TraceSQLStatementWithArgs TraceSQLMode = "statement_with_args"
)

type Tracer 

type Tracer interface {
	Start(context.Context, string, ...SpanOption) (context.Context, Span)
}

Tracer starts spans.

type TracerProvider 

type TracerProvider interface {
	Tracer(name string) Tracer
}

TracerProvider creates named tracers.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.