Documentation
¶
Index ¶
- Variables
- func DatabaseUnreachable(openErr error) error
- func ResetDiagnostics()
- func RouteDiagnostics(logger loggingcontract.Logger)
- type ConnectionParameters
- type ConnectionParamsdeprecated
- type ContextOpener
- type Manager
- type ManagerRegistry
- func (instance *ManagerRegistry) Close() error
- func (instance *ManagerRegistry) CloseMigrationDatabase(name string) error
- func (instance *ManagerRegistry) CloseWithContext(closeContext context.Context) error
- func (instance *ManagerRegistry) Database(name string) (*bun.DB, error)
- func (instance *ManagerRegistry) DefaultDatabase() (*bun.DB, error)
- func (instance *ManagerRegistry) DefaultManager() (*Manager, error)
- func (instance *ManagerRegistry) HasProviderDefinition(name string) bool
- func (instance *ManagerRegistry) Manager(name string) (*Manager, error)
- func (instance *ManagerRegistry) MigrationDatabase(name string) (*bun.DB, bool, error)
- func (instance *ManagerRegistry) MustDatabase(name string) *bun.DB
- func (instance *ManagerRegistry) MustDefaultDatabase() *bun.DB
- func (instance *ManagerRegistry) MustDefaultManager() *Manager
- func (instance *ManagerRegistry) MustManager(name string) *Manager
- func (instance *ManagerRegistry) SetLogger(logger loggingcontract.Logger) error
- type MigrationContextOpener
- type MigrationProvider
- type Provider
- type ProviderDefinition
- type ReadWriteSplitter
- type ReadWriteSplitterOption
Constants ¶
This section is empty.
Variables ¶
var ErrDatabaseUnreachable = errors.New("database unreachable")
ErrDatabaseUnreachable is the class of an open failure the provider classified as TRANSIENT — a dial refused, a name that would not resolve, a timeout — and could not get past: the outage a ReadWriteSplitter absorbs by reading from the primary. Every other open failure is terminal by nature — a parameter the provider refused, a password the server refused, a database that does not exist — and reaches the caller as it is, so a replica whose configuration is wrong is refused instead of served silently from the primary. A provider that does not mark its failures has them read as terminal, which is the direction that surfaces a misconfiguration.
var ErrLoggerIsRequired = errors.New("logger is required")
var ErrManagerRegistryClosed = errors.New("manager registry is closed")
var ErrMultipleDefaultProviderDefinitions = errors.New("multiple provider definitions are marked as default")
var ErrNoProviderDefinitions = errors.New("no provider definitions are registered")
var ErrProviderDefinitionNameIsRequired = errors.New("provider definition name is required")
var ErrProviderDefinitionNameMustBeUnique = errors.New("provider definition name must be unique")
var ErrProviderDefinitionNotFound = errors.New("provider definition not found")
var ErrProviderIsRequired = errors.New("provider is required")
var ErrProviderReturnedNilDatabase = errors.New("provider returned neither a database nor an error")
Functions ¶
func DatabaseUnreachable ¶ added in v3.6.0
DatabaseUnreachable files an open failure under ErrDatabaseUnreachable. The link sits under the provider's exception as its cause — the exception keeps its message and its context — and unwraps to the failure the provider saw, so errors.Is answers the class, errors.As still reaches the driver error, and a journal that renders the cause chain reads the class once, where the driver failure stood.
func ResetDiagnostics ¶ added in v3.6.0
func ResetDiagnostics()
ResetDiagnostics hands bun's diagnostic channel back to standard error, whoever routed it, so a teardown writes nothing into a journal that is closing and a process hosting melody can take the channel for its own logger. Calling it when nothing is routed changes nothing. A registry's own teardown does not call it: the registry retires its logger and hands the channel back only when the live routing is that logger's, so one registry closing does not take the channel from another.
func RouteDiagnostics ¶ added in v3.6.0
func RouteDiagnostics(logger loggingcontract.Logger)
RouteDiagnostics sends bun's own diagnostic channel, which reports declaration mistakes such as an unknown struct tag option, to the application's journal as warning records. Bun's logger is set once for the process, to a forwarder whose destination each routing on a different logger replaces, so a rebuilt application takes the channel back; a routing on the logger already installed changes nothing, and a nil or typed-nil logger routes nothing. The mysql dialect's server-version line goes through the standard library's default logger and is not reached; see the mysql readme.
Types ¶
type ConnectionParameters ¶ added in v3.5.0
type ConnectionParameters struct {
Host string
Port string
Database string
User string
Password string
}
func (*ConnectionParameters) SafeContext ¶ added in v3.5.0
func (instance *ConnectionParameters) SafeContext() map[string]any
type ConnectionParams
deprecated
type ConnectionParams = ConnectionParameters
Deprecated: use ConnectionParameters.
type ContextOpener ¶ added in v3.6.0
type ContextOpener interface {
OpenContext(ctx context.Context, params ConnectionParameters, logger loggingcontract.Logger) (*bun.DB, error)
}
ContextOpener is the optional capability of opening under a caller's context: the retry loop between attempts sleeps on the context as well as the clock, so a shutdown that cancels it reaches a dial in flight instead of sleeping through the whole retry budget — the exact window in which supervisors send their signals. The registry prefers it whenever the provider implements it, handing a child of the context it was constructed with, which CloseWithContext also cancels, so no open goes on dialling after the registry is gone.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
func (*Manager) DefinitionName ¶
type ManagerRegistry ¶
type ManagerRegistry struct {
// contains filtered or unexported fields
}
func NewManagerRegistry ¶
func NewManagerRegistry(logger loggingcontract.Logger, providerDefinitions ...ProviderDefinition) (*ManagerRegistry, error)
NewManagerRegistry is container-level deliberately: a *bun.DB is a process-lifetime pool, not a pool per scope.
func NewManagerRegistryWithContext ¶ added in v3.6.0
func NewManagerRegistryWithContext(ctx context.Context, logger loggingcontract.Logger, providerDefinitions ...ProviderDefinition) (*ManagerRegistry, error)
func (*ManagerRegistry) Close ¶
func (instance *ManagerRegistry) Close() error
func (*ManagerRegistry) CloseMigrationDatabase ¶ added in v3.6.0
func (instance *ManagerRegistry) CloseMigrationDatabase(name string) error
func (*ManagerRegistry) CloseWithContext ¶ added in v3.6.0
func (instance *ManagerRegistry) CloseWithContext(closeContext context.Context) error
CloseWithContext tears the pools down whatever the deadline says; the deadline bounds only the wait for opens in flight.
func (*ManagerRegistry) Database ¶
func (instance *ManagerRegistry) Database(name string) (*bun.DB, error)
func (*ManagerRegistry) DefaultDatabase ¶
func (instance *ManagerRegistry) DefaultDatabase() (*bun.DB, error)
func (*ManagerRegistry) DefaultManager ¶
func (instance *ManagerRegistry) DefaultManager() (*Manager, error)
func (*ManagerRegistry) HasProviderDefinition ¶ added in v3.6.0
func (instance *ManagerRegistry) HasProviderDefinition(name string) bool
func (*ManagerRegistry) Manager ¶
func (instance *ManagerRegistry) Manager(name string) (*Manager, error)
func (*ManagerRegistry) MigrationDatabase ¶ added in v3.6.0
MigrationDatabase takes a hold when it answers the dedicated connection; CloseMigrationDatabase releases the hold.
func (*ManagerRegistry) MustDatabase ¶
func (instance *ManagerRegistry) MustDatabase(name string) *bun.DB
func (*ManagerRegistry) MustDefaultDatabase ¶
func (instance *ManagerRegistry) MustDefaultDatabase() *bun.DB
func (*ManagerRegistry) MustDefaultManager ¶
func (instance *ManagerRegistry) MustDefaultManager() *Manager
func (*ManagerRegistry) MustManager ¶
func (instance *ManagerRegistry) MustManager(name string) *Manager
func (*ManagerRegistry) SetLogger ¶ added in v3.6.0
func (instance *ManagerRegistry) SetLogger(logger loggingcontract.Logger) error
type MigrationContextOpener ¶ added in v3.6.0
type MigrationContextOpener interface {
OpenForMigrationContext(ctx context.Context, params ConnectionParameters, logger loggingcontract.Logger) (*bun.DB, error)
}
MigrationContextOpener is what ContextOpener is to Open: the migration open under the caller's context, so a db:migrate that receives SIGTERM against a down database refuses at the first cancellable step. The registry asks for it only of a provider that also implements MigrationProvider, and prefers it there; implemented alone it is never called, the migration commands running on the pooled connection.
type MigrationProvider ¶ added in v3.6.0
type MigrationProvider interface {
OpenForMigration(params ConnectionParameters, logger loggingcontract.Logger) (*bun.DB, error)
}
MigrationProvider is the optional capability of opening a connection tuned for migrations: the pool a provider opens for request traffic carries driver-level read and write deadlines sized for requests, and a legitimate DDL statement that runs past them — an ALTER TABLE adding constraints on a large table — is cut mid-statement with "invalid connection", outside any transaction MySQL would roll back. A provider that implements this opens the same database with those deadlines lifted; the migration commands prefer it and fall back to the ordinary connection when the capability is absent.
type Provider ¶
type Provider interface {
Open(params ConnectionParameters, logger loggingcontract.Logger) (*bun.DB, error)
}
Provider opens the connection pool a definition names. Open answers a fresh pool whose ownership transfers to the caller: the registry closes every database it decides not to keep — one handed back beside an error, one that loses a duplicate migration open, one that lands after Close — so an implementation handing out a shared or memoized *bun.DB would have its live pool closed underneath it.
type ProviderDefinition ¶
type ProviderDefinition struct {
Name string
Provider Provider
Params ConnectionParameters
IsDefault bool
}
type ReadWriteSplitter ¶ added in v3.1.0
type ReadWriteSplitter struct {
// contains filtered or unexported fields
}
func NewReadWriteSplitter ¶ added in v3.1.0
func NewReadWriteSplitter(registry *ManagerRegistry, primaryName string, replicaNames ...string) *ReadWriteSplitter
NewReadWriteSplitter routes writes to the primary and reads round-robin over the replicas.
func NewReadWriteSplitterWithOptions ¶ added in v3.6.0
func NewReadWriteSplitterWithOptions(registry *ManagerRegistry, primaryName string, replicaNames []string, options ...ReadWriteSplitterOption) *ReadWriteSplitter
func (*ReadWriteSplitter) Reader ¶ added in v3.1.0
func (instance *ReadWriteSplitter) Reader() (*bun.DB, error)
Reader falls back to the primary only for an unreachable replica; every other failure is refused.
func (*ReadWriteSplitter) ReaderName ¶ added in v3.1.0
func (instance *ReadWriteSplitter) ReaderName() string
func (*ReadWriteSplitter) Writer ¶ added in v3.1.0
func (instance *ReadWriteSplitter) Writer() (*bun.DB, error)
func (*ReadWriteSplitter) WriterName ¶ added in v3.1.0
func (instance *ReadWriteSplitter) WriterName() string
type ReadWriteSplitterOption ¶ added in v3.6.0
type ReadWriteSplitterOption func(splitter *ReadWriteSplitter)
func WithReplicaRetryInterval ¶ added in v3.6.0
func WithReplicaRetryInterval(interval time.Duration) ReadWriteSplitterOption
WithReplicaRetryInterval: a zero interval keeps the default of five seconds; a negative one is a wiring error.