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). Columns named by r3.IncrementOnConflict are added to rather than overwritten, and leave the default update set. 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