Documentation
¶
Index ¶
- Variables
- func RouteDiagnostics(logger loggingcontract.Logger)
- type ContextOpener
- type Manager
- type ManagerRegistry
- func (instance *ManagerRegistry) Close() 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) 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
- type MigrationContextOpener
- type MigrationProvider
- type Provider
- type ProviderDefinition
- type SecretParameterProvider
Constants ¶
This section is empty.
Variables ¶
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")
var ErrResolverIsRequired = errors.New("resolver is required")
Functions ¶
func RouteDiagnostics ¶ added in v1.1.0
func RouteDiagnostics(logger loggingcontract.Logger)
RouteDiagnostics sends bun's own diagnostic channel, which reports declaration mistakes such as an unknown struct tag option, an unknown on_update or on_delete rule or a query with arguments and no placeholders, to the application's journal as warning records instead of standard error. Bun's logger is one variable for the process, so the first provider to open wins it for the process's whole life and later calls are ignored: in a process that rebuilds its application, a test binary above all, a later lifecycle's diagnostics go to the first lifecycle's logger and are dropped if that logger is closed. It is called from the providers, so a binary that never opens a database takes no setting. 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 ContextOpener ¶ added in v1.1.0
type ContextOpener interface {
OpenContext(ctx context.Context, resolver containercontract.Resolver) (*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 the context it was constructed with.
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(resolver containercontract.Resolver, providerDefinitions ...ProviderDefinition) (*ManagerRegistry, error)
NewManagerRegistry builds a container-level registry over lazily-dialed pools. Container-level deliberately: a *bun.DB is a connection pool — the process-lifetime shape of database/sql — and per-unit work takes a transaction or a Conn from the pool, not a pool per scope. The lazy opens replay through the container behind the given resolver (asked via the ContainerCarrier door), never through the resolution context that built the registry.
func NewManagerRegistryWithContext ¶ added in v1.1.0
func NewManagerRegistryWithContext(ctx context.Context, resolver containercontract.Resolver, providerDefinitions ...ProviderDefinition) (*ManagerRegistry, error)
NewManagerRegistryWithContext additionally binds the registry to the given context: a provider that implements ContextOpener has its lazy opens run under it, so a shutdown that cancels the context refuses an open not yet started, reaches the attempt's cancellable steps — the configuration hook, the boot ping, a retry sleep — in flight, its dial and handshake bounded by the connect timeout under the context. A nil context reads as context.Background(), the exact behaviour of NewManagerRegistry.
func (*ManagerRegistry) Close ¶
func (instance *ManagerRegistry) Close() error
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) Manager ¶
func (instance *ManagerRegistry) Manager(name string) (*Manager, error)
func (*ManagerRegistry) MigrationDatabase ¶ added in v1.1.0
MigrationDatabase answers the connection the migration commands run on: a dedicated one with the driver deadlines lifted when the provider implements MigrationProvider, reported through the second return, and the pooled connection otherwise, since a DDL statement cut by a request deadline is not rolled back by MySQL. An empty name selects the default definition; the dedicated database is opened once per name, cached, and closed by Close.
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
type MigrationContextOpener ¶ added in v1.1.0
type MigrationContextOpener interface {
OpenForMigrationContext(ctx context.Context, resolver containercontract.Resolver) (*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 v1.1.0
type MigrationProvider interface {
OpenForMigration(resolver containercontract.Resolver) (*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(resolver containercontract.Resolver) (*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 SecretParameterProvider ¶ added in v1.1.0
type SecretParameterProvider interface {
SecretParameterNames() []string
}
SecretParameterProvider is the optional capability of naming the configuration parameters that hold this provider's credentials. The registry asks every definition at construction and marks each through the configuration's MarkSecret, so a process that never dials, a debug:parameters run above all, still redacts the password; a provider without it is not asked.