Documentation
¶
Index ¶
- Constants
- Variables
- func GetContext(ctx context.Context) (bun.IDB, error)
- func NewContext(ctx context.Context, config Config) (context.Context, error)
- func NewContextSchema(ctx context.Context, config Config, schema string, create bool) (context.Context, error)
- func NewContextTest(ctx context.Context, config Config) (context.Context, error)
- func Ping(ctx context.Context, client *bun.DB) error
- func RunDBTest(t *testing.T, config Config, migrations fs.FS, callback TransactionalTestFunc)
- func RunInTx(ctx context.Context, opts *sql.TxOptions, ...) error
- func RunIsolatedTransactionalTest(t *testing.T, config Config, migrations fs.FS, callback TransactionalTestFunc)
- func RunMigrations(ctx context.Context, db *bun.DB, migrations fs.FS) error
- func RunMigrationsContext(ctx context.Context, migrations fs.FS) error
- func RunTransactionalTest(t *testing.T, config Config, callback TransactionalTestFunc)
- func TransferContext(baseCtx, destCtx context.Context) context.Context
- type Config
- type ContextKey
- type PassthroughTx
- type TransactionalTestFunc
Constants ¶
const ( PingTimeout = 10 * time.Second // PingRetryInterval is the wait between failed ping attempts. Without it, // Ping would tight-loop reconnects on an unreachable database for the // duration of PingTimeout. PingRetryInterval = 100 * time.Millisecond )
const NameLen = 31
Variables ¶
var ErrNoDbInContext = errors.New("context does not contain a bun.DB")
var ErrNoIDBInContext = errors.New("context does not contain a bun.IDB")
ErrNoIDBInContext is returned by GetContext when the supplied context does not carry a bun.IDB value (it was never seeded via NewContext / one of its variants). It is sibling to ErrNoDbInContext in migrator.go, which signals the stricter "found an IDB but it isn't a *bun.DB" case.
Functions ¶
func NewContextSchema ¶
func NewContextTest ¶
func Ping ¶
Ping a database connection until it succeeds or the timeout is reached. Honours ctx cancellation both for the PingContext call and for the wait between retries.
func RunDBTest ¶ added in v0.22.0
RunDBTest runs callback against its own freshly created PostgreSQL database, cloned from a migrated template via `CREATE DATABASE … TEMPLATE`. Unlike RunTransactionalTest (shared schema, rolled-back transaction — correct only when tests run serially) every RunDBTest call is physically isolated, so the caller may freely mark the test and its sub-tests t.Parallel() even when they reuse the same fixture keys.
The cost model is "migrate once, clone many": the migration set is applied a single time into a template database whose name is a hash of the migrations, and each test gets a fast file-level copy of it. The per-test database is dropped (WITH FORCE) in t.Cleanup; the template is left in place and reused across runs as long as the migrations are unchanged.
config must expose Options() []pgdriver.Option (postgrespresets.Default does). callback receives a context carrying a real *bun.DB for the per-test database, retrievable with GetContext.
func RunIsolatedTransactionalTest ¶
func RunIsolatedTransactionalTest(t *testing.T, config Config, migrations fs.FS, callback TransactionalTestFunc)
RunIsolatedTransactionalTest runs test in a temporary throwaway schema. This allows for operations that cannot be performed concurrently in a transactional context, such as refreshing materialized views.
This method uses a separate schema, rather than a new database, so existing extensions are still available. It still requires to rerun the whole migration process, so unless needed, RunTransactionalTest should be preferred.
func RunMigrations ¶
RunMigrations runs all the migrations found in the provided filesystem.
func RunMigrationsContext ¶
RunMigrationsContext runs all the migrations found in the provided filesystem, using the database connection from the context.
func RunTransactionalTest ¶
func RunTransactionalTest(t *testing.T, config Config, callback TransactionalTestFunc)
RunTransactionalTest creates a special transactional context for testing. This context uses the PassthroughTx implementation, that allows for concurrent tests with the same database connection. It discards sub-transactions to prevent deadlocks.
Types ¶
type ContextKey ¶
type ContextKey struct{}
type PassthroughTx ¶
PassthroughTx is an extension of bun.Tx that prevents sub contexts from creating new sub-transactions.
Because postgresql does not support nested transactions, bun will create savepoints instead. Unlike top-level transactions, savepoints don't support parallelism (as they are part of the same query).
For testing, where the whole application is wrapped in a transaction, this can cause issues where multiple parallel calls to a method will attempt concurrent write on the same transaction.
To get around it, this package provides an alternative bun.IDB implementation, that does not create new transactions.
func NewPassthroughTx ¶
func NewPassthroughTx(tx bun.Tx) *PassthroughTx
func (*PassthroughTx) Commit ¶
func (tx *PassthroughTx) Commit() error
func (*PassthroughTx) Rollback ¶
func (tx *PassthroughTx) Rollback() error
Source Files
Directories