Documentation
¶
Overview ¶
Package r3bun provides an r3.CRUD[T, ID] driver backed by Bun, a SQL-first Go ORM for PostgreSQL, MySQL, MSSQL, and SQLite.
Driver: github.com/uptrace/bun Source: https://github.com/uptrace/bun
Supported r3 features:
- Full CRUD (Create, Get, List, Update, Delete)
- Filters, Sorts, Pagination via the r3 SQL dialect
- Preloads via Bun's Relation() (belongs-to, has-one, has-many, many-to-many)
- IncludeTrashed via Bun's WhereAllWithDeleted() (requires soft-delete model setup)
- Restore and HardDelete via the features/softdelete SoftDeleter interface
- Thread-safe default queries (SetDefaultListQuery, SetDefaultGetQuery)
- Raw escape hatch (BunRaw) for custom bun.SelectQuery usage
Limitations / notes:
- Bun wraps database/sql natively; use db.DB (the underlying *sql.DB) for goose migrations or any raw database/sql usage.
- Model structs must embed bun.BaseModel with a table tag and use `bun` struct tags.
- Aggregate / custom-shape queries should use Raw().Scan() into a dedicated struct, since Raw().Find() scans into []T and Bun rejects unknown columns.
- Bun is the recommended successor to go-pg by the same authors.
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)
- type BunRaw
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewBunQuerier ¶
NewBunQuerier creates a read-only Bun-based repository. Returns r3.Querier — a compile-time guarantee of read-only access.
Types ¶
type BunCRUD ¶
type BunCRUD[T any, ID comparable] struct { enginesql.DefaultsManager Config r3.Config // contains filtered or unexported fields }
BunCRUD is a CRUD repository based on Bun's *bun.DB. Internally it uses bun.IDB so that it can operate within transactions as well.
func NewBunCRUD ¶
NewBunCRUD creates a new Bun-based CRUD repository.
Accepts optional r3.Option values for framework-level configuration.
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.
type BunRaw ¶
BunRaw is a Bun wrapper that allows calling any Bun query. Is considered to be embedded in BunCRUD.
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