Documentation
¶
Overview ¶
Package r3bun is an r3.CRUD[T, ID] driver backed by Bun (github.com/uptrace/bun), a SQL-first ORM for PostgreSQL, MySQL, MSSQL, and SQLite. It maps preloads onto Bun's Relation(), IncludeTrashed onto WhereAllWithDeleted() (needs soft-delete model setup), and exposes Restore/HardDelete.
Notes:
- Models must embed bun.BaseModel (with a table tag) and use `bun` tags.
- Bun wraps database/sql natively; use db.DB for goose migrations or raw usage.
- For aggregate / custom-shape rows use Raw().Scan() into a dedicated struct; Raw().Find() scans into []T and Bun rejects unknown columns.
Index ¶
- func NewBunQuerier[T any, ID comparable](db *bun.DB, opts ...r3.Option) r3.Querier[T, ID]
- type BunCRUD
- func (r *BunCRUD[T, ID]) Aggregate(ctx context.Context, qarg ...r3.Query) ([]r3.AggregateRow, error)
- func (r *BunCRUD[T, ID]) BeginTx(ctx context.Context) (r3.TxCRUD[T, ID], error)
- func (r *BunCRUD[T, ID]) Count(ctx context.Context, qarg ...r3.Query) (int64, error)
- func (r *BunCRUD[T, ID]) Create(ctx context.Context, entity T) (T, error)
- func (r *BunCRUD[T, ID]) DB() *bun.DB
- func (r *BunCRUD[T, ID]) Delete(ctx context.Context, id ID) error
- func (r *BunCRUD[T, ID]) Get(ctx context.Context, id ID, qarg ...r3.Query) (T, error)
- func (r *BunCRUD[T, ID]) HardDelete(ctx context.Context, id ID) error
- func (r *BunCRUD[T, ID]) List(ctx context.Context, qarg ...r3.Query) ([]T, int64, error)
- func (r *BunCRUD[T, ID]) Patch(ctx context.Context, entity T, fields r3.Fields) (T, error)
- func (r *BunCRUD[T, ID]) Raw() *BunRaw[T, ID]
- func (r *BunCRUD[T, ID]) Restore(ctx context.Context, id ID) error
- func (r *BunCRUD[T, ID]) Update(ctx context.Context, entity T) (T, error)
- func (r *BunCRUD[T, ID]) Upsert(ctx context.Context, entity T, opts ...r3.UpsertOption) (T, error)
- type BunRaw
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewBunQuerier ¶
NewBunQuerier builds a read-only Bun repository (r3.Querier enforces it).
Types ¶
type BunCRUD ¶
type BunCRUD[T any, ID comparable] struct { enginesql.DefaultsManager Config r3.Config // contains filtered or unexported fields }
BunCRUD is a Bun repository. It holds bun.IDB (not *bun.DB) so the same code runs against a transaction.
func NewBunCRUD ¶
NewBunCRUD builds a Bun-based repository.
func (*BunCRUD[T, ID]) Aggregate ¶ added in v0.0.3
func (r *BunCRUD[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 (*BunCRUD[T, ID]) BeginTx ¶
BeginTx starts a Bun transaction and returns an r3.TxCRUD scoped to it. The caller must call Commit or Rollback on the returned TxCRUD.
func (*BunCRUD[T, ID]) DB ¶
DB returns the underlying *bun.DB for advanced usage. Panics if BunCRUD is operating inside a transaction.
func (*BunCRUD[T, ID]) HardDelete ¶
HardDelete permanently removes a record, bypassing Bun's soft-delete.
func (*BunCRUD[T, ID]) Restore ¶
Restore un-deletes a soft-deleted record by clearing its soft-delete column.
func (*BunCRUD[T, ID]) Upsert ¶ added in v0.0.11
Upsert inserts entity, or on a conflict with the target columns updates the named columns in place, then returns the stored row. It implements r3.Upserter via SQL `INSERT ... ON CONFLICT (...) DO UPDATE SET ... RETURNING *`.
The conflict target defaults to the primary key; the update set defaults to every column except the primary key, the conflict columns, and created_at (never overwritten). An explicit UpdateOnConflict set is validated like Patch (unknown/PK/soft-delete columns are rejected). Timestamp bumping on the update branch is left to the database (default/trigger), matching this driver's create/update behavior. Requires a dialect with ON CONFLICT and RETURNING (Postgres, SQLite).
type BunRaw ¶
BunRaw is the Bun escape hatch, exposing any Bun query via Find/Scan callbacks.
func NewBunRaw ¶
func NewBunRaw[T any, ID comparable](db bun.IDB) *BunRaw[T, ID]
NewBunRaw creates a new BunRaw instance.
func (*BunRaw[T, ID]) Find ¶
func (r *BunRaw[T, ID]) Find(ctx context.Context, cb func(*bun.SelectQuery) *bun.SelectQuery) ([]T, error)
Find executes a custom select query and returns the results. The callback receives a *bun.SelectQuery to build a custom query.
Source Files