Documentation
¶
Overview ¶
Package r3gorm provides an r3.CRUD[T, ID] driver backed by GORM.
Driver: gorm.io/gorm Source: https://gorm.io
Supported r3 features:
- Full CRUD (Create, Get, List, Update, Patch, Delete)
- Filters, Sorts, Pagination via the r3 SQL dialect
- Preloads via GORM's Preload()
- Soft-delete via GORM's Unscoped()
- Restore and HardDelete via the features/softdelete SoftDeleter interface
- Transactions via the r3.Transactor interface
- Thread-safe default queries (SetDefaultListQuery, SetDefaultGetQuery)
- Raw escape hatch (GormRaw) for custom gorm.DB usage
Index ¶
- Variables
- func DBOf[T any, ID comparable](repo r3.CRUD[T, ID]) (*gorm.DB, error)
- func NewGormQuerier[T any, ID comparable](db *gorm.DB, opts ...r3.Option) r3.Querier[T, ID]
- type GormCRUD
- func (r *GormCRUD[T, ID]) Aggregate(ctx context.Context, qarg ...r3.Query) ([]r3.AggregateRow, error)
- func (r *GormCRUD[T, ID]) AggregateThroughRelation(ctx context.Context, relation string, qarg ...r3.Query) ([]r3.AggregateRow, error)
- func (r *GormCRUD[T, ID]) BeginTx(ctx context.Context) (r3.TxCRUD[T, ID], error)
- func (r *GormCRUD[T, ID]) Count(ctx context.Context, qarg ...r3.Query) (int64, error)
- func (r *GormCRUD[T, ID]) Create(ctx context.Context, entity T) (T, error)
- func (r *GormCRUD[T, ID]) DB() *gorm.DB
- func (r *GormCRUD[T, ID]) Delete(ctx context.Context, id ID) error
- func (r *GormCRUD[T, ID]) Get(ctx context.Context, id ID, qarg ...r3.Query) (T, error)
- func (r *GormCRUD[T, ID]) HardDelete(ctx context.Context, id ID) error
- func (r *GormCRUD[T, ID]) List(ctx context.Context, qarg ...r3.Query) ([]T, int64, error)
- func (r *GormCRUD[T, ID]) Patch(ctx context.Context, entity T, fields r3.Fields) (T, error)
- func (r *GormCRUD[T, ID]) PatchWhere(ctx context.Context, filters r3.Filters, entity T, fields r3.Fields) (int64, error)
- func (r *GormCRUD[T, ID]) Raw() *GormRaw[T, ID]
- func (r *GormCRUD[T, ID]) Restore(ctx context.Context, id ID) error
- func (r *GormCRUD[T, ID]) Update(ctx context.Context, entity T) (T, error)
- func (r *GormCRUD[T, ID]) Upsert(ctx context.Context, entity T, opts ...r3.UpsertOption) (T, error)
- type GormRaw
- type RawAccessor
Constants ¶
This section is empty.
Variables ¶
var ErrRawNotSupported = errors.New("r3gorm: raw driver access not supported")
ErrRawNotSupported is returned by RawOf and DBOf when the repository is not (and does not unwrap to) a gorm-backed repository. It is driver-specific and deliberately lives here rather than in core r3.
Functions ¶
func DBOf ¶ added in v0.0.6
DBOf returns the underlying *gorm.DB (full raw access: .Exec, .Raw(sql), …), with the same unwrap-through-decorators and error contract as RawOf. Use it only when GormRaw's builder callback is not enough.
The RawOf caveat applies here more sharply: the *gorm.DB bypasses the entire feature stack. Prefer high-level methods for writes; use DBOf for reads or queries that neither a repo method nor RawOf's builder can express.
func NewGormQuerier ¶
NewGormQuerier creates a read-only GORM-based repository. Returns r3.Querier — a compile-time guarantee of read-only access.
Types ¶
type GormCRUD ¶
type GormCRUD[T any, ID comparable] struct { enginesql.DefaultsManager Config r3.Config // contains filtered or unexported fields }
GormCRUD is a CRUD repository based on gorm.DB.
func NewGormCRUD ¶
NewGormCRUD creates a new GORM-based CRUD repository.
Accepts optional r3.Option values for framework-level configuration.
func (*GormCRUD[T, ID]) Aggregate ¶ added in v0.0.3
func (r *GormCRUD[T, ID]) Aggregate(ctx context.Context, qarg ...r3.Query) ([]r3.AggregateRow, error)
Aggregate computes grouped aggregates over the records matching the query. See r3.Aggregator for the query semantics.
func (*GormCRUD[T, ID]) AggregateThroughRelation ¶ added in v0.0.5
func (r *GormCRUD[T, ID]) AggregateThroughRelation( ctx context.Context, relation string, qarg ...r3.Query, ) ([]r3.AggregateRow, error)
AggregateThroughRelation aggregates the entity's related rows through a declared relation, grouped and folded over the related base table (the child table for has-many, the join table for many-to-many). See r3.RelationAggregator for the full query semantics.
func (*GormCRUD[T, ID]) BeginTx ¶
BeginTx starts a GORM transaction and returns an r3.TxCRUD scoped to it. The caller must call Commit or Rollback on the returned TxCRUD.
func (*GormCRUD[T, ID]) HardDelete ¶
HardDelete permanently removes a record, bypassing GORM's soft-delete.
func (*GormCRUD[T, ID]) PatchWhere ¶ added in v0.0.4
func (r *GormCRUD[T, ID]) PatchWhere( ctx context.Context, filters r3.Filters, entity T, fields r3.Fields, ) (int64, error)
PatchWhere sets the given fields (to entity's values) on every row matching filters and returns the affected-row count. It is the multi-row analogue of Patch: the column set is validated and capability-gated identically (ValidatePatchColumns + RequireMutableColumns), managed updated_at is bumped, and the write guard bypass is honored — but rows are selected by filters instead of by primary key.
Filters are validated against the schema and reuse the same filter→SQL translation as List (including relationship "has" filter lowering). Soft-delete exclusion follows GORM's default model scoping.
func (*GormCRUD[T, ID]) Restore ¶
Restore un-deletes a soft-deleted record by clearing its soft-delete column.
func (*GormCRUD[T, ID]) Upsert ¶ added in v0.0.4
Upsert inserts entity, or updates the colliding row when it conflicts on the conflict target (the primary key by default). It maps directly onto GORM's clause.OnConflict — the same construction application code hand-writes today.
The insert branch obeys Creatable and stamps created_at/updated_at (via the shared writeOmit path); the on-conflict update branch obeys Mutable and bumps updated_at. The write guard bypass (r3.WithoutWriteGuard) is honored. The stored row is re-fetched by the conflict target and returned, so the result reflects the update, defaults, and triggers even on a collision.
Upsert is a row-level operation and does not sync associations; use Create/Update for entities carrying related rows.
type GormRaw ¶
GormRaw is a gorm wrapper that allows call any gorm request. Is considered to be embedded in GormCRUD.
func NewGormRaw ¶
func NewGormRaw[T any, ID comparable](db *gorm.DB) *GormRaw[T, ID]
func RawOf ¶ added in v0.0.6
RawOf returns the typed gorm raw-builder for repo, walking any decorator chain (via r3.As) down to the gorm backend. It returns ErrRawNotSupported if repo is not gorm-backed. This lets a service that holds its repo as the backend-agnostic r3.CRUD[T, ID] interface reach the raw hatch without a hand-written type assertion.
The builder runs BELOW the feature decorators (history, permissions, i18n, …): reads through it are fine, but a WRITE issued via the raw builder is neither audited, permission-checked, nor stale-marked. Prefer a high-level method for writes, and reach for RawOf only for reads or queries that no repo method can express.
type RawAccessor ¶ added in v0.0.6
type RawAccessor[T any, ID comparable] interface { Raw() *GormRaw[T, ID] DB() *gorm.DB }
RawAccessor is the GORM driver escape hatch: reach the typed gorm builder (GormRaw, via Raw) or the underlying *gorm.DB (via DB) of a gorm-backed repo. *GormCRUD[T, ID] already satisfies it — the interface exists so RawOf/DBOf can find it through a decorator chain.
Source Files