Documentation
¶
Index ¶
- func BuildConnection(config config.Config, logger contractslogger.Logger, pool database.Pool, ...) (*sql.DB, *instrumentationdatabase.Instrument, error)
- func CausedByConcurrencyError(err error) bool
- func CausedByLostConnection(err error) bool
- func CloseConnections()
- func Escape(driver string, value any, binary bool) (string, error)
- func EscapeWithDialect(dialect contractsdriver.Dialect, driver string, value any, binary bool) (string, error)
- func Instrument(connection string, pools ...database.Pool) *instrumentationdatabase.Instrument
- func PurgeConnection(name string, pools ...database.Pool) error
- func Reader(connection string, pools ...database.Pool) *sql.DB
- func ResetConnections()
- func ResolveDialect(source contractsdriver.Driver) (contractsdriver.Dialect, error)
- func TransactionOptions(config config.Config, connection string) (*sql.TxOptions, error)
- type Connection
- func (r *Connection) Driver() string
- func (r *Connection) Instrument() *instrumentationdatabase.Instrument
- func (r *Connection) IsCurrent() bool
- func (r *Connection) Name() string
- func (r *Connection) Purge() error
- func (r *Connection) Reader() *sql.DB
- func (r *Connection) ServerVersion(ctx context.Context) (string, error)
- func (r *Connection) SupportsServerVersion() bool
- func (r *Connection) Writer() *sql.DB
- type QueryComponents
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildConnection ¶
func BuildConnection(config config.Config, logger contractslogger.Logger, pool database.Pool, connection string, telemetryResolver contractstelemetry.Resolver, dialects ...contractsdriver.Dialect) (*sql.DB, *instrumentationdatabase.Instrument, error)
BuildConnection opens and caches a connection's writer pool.
The framework opens the pool itself from the connection's fields, which is what the dialector a driver module used to hand over did. A connection with no database name opens nothing and reports (nil, nil, nil): that is a fresh application before any credentials exist, and callers read it as "no database" rather than as a failure.
func CausedByConcurrencyError ¶
Laravel's detectors recognize database failures by SQLSTATE and driver messages. Native Go driver codes are checked before the upstream message corpus.
func CausedByLostConnection ¶
func CloseConnections ¶
func CloseConnections()
CloseConnections drops the cached connections, unregisters their telemetry and closes the pools, the reader pools included. Call it only when the connections are idle.
func Escape ¶
Escape produces a scalar SQL literal. Bound execution continues to use driver parameters.
func EscapeWithDialect ¶
func Instrument ¶
func Instrument(connection string, pools ...database.Pool) *instrumentationdatabase.Instrument
Instrument returns the telemetry instrument cached for a logical connection. Supply its pool when the driver's configured source has a different name. Managed callers use Connection.Instrument.
func PurgeConnection ¶
PurgeConnection removes one logical connection. Supply the driver's pool when its configured connection name differs from name; handles can call Connection.Purge without resolving it again. database/sql lets already leased connections finish their transactions while refusing new work.
func Reader ¶
Reader returns a logical connection's cached replica, or nil when it has none. Supply its pool when the driver's configured source has a different name. Managed callers use Connection.Reader.
func ResetConnections ¶
func ResetConnections()
ResetConnections drops the cached connections and unregisters their telemetry, leaving the pools open for callers that may still hold them. Reader pools are dropped from the cache as well, and likewise left open.
func ResolveDialect ¶
func ResolveDialect(source contractsdriver.Driver) (contractsdriver.Dialect, error)
func TransactionOptions ¶
TransactionOptions returns the options a transaction on this connection is opened with, or nil when the connection asks for the driver's own default.
The level comes from database.connections.<name>.isolation_level and is named the way Laravel names it — "read committed", "repeatable read", "serializable", "read uncommitted" — so an application migrating from Laravel keeps its spelling. Case and the separator are not significant: "READ-COMMITTED" and "read_committed" both mean the same level.
A value that names no level is reported rather than ignored: silently opening a transaction at a weaker level than the application asked for is the kind of failure that only shows up under concurrency.
Types ¶
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection is the framework's handle on one configured database connection. It owns the pools the framework executes its compiled statements through — one writer pool and, when the connection is configured with replicas, one reader pool.
Read/write routing lives here: a statement that only reads rows runs on the reader pool and every other one on the writer. The pools are opened by this package from the connection's own fields, so no ORM session sits between the framework and the database.
func Open ¶
func Open(config config.Config, logger contractslogger.Logger, pool database.Pool, connection string, telemetryResolver contractstelemetry.Resolver, dialects ...contractsdriver.Dialect) (*Connection, error)
Open returns the connection for a configured pool, building and caching it on first use.
It returns a nil connection, without an error, when the connection carries no database name: that is the state of a fresh application before any credentials exist, and callers treat it as "no database" rather than as a failure.
func (*Connection) Driver ¶
func (r *Connection) Driver() string
Driver returns the driver name the connection is configured with.
func (*Connection) Instrument ¶
func (r *Connection) Instrument() *instrumentationdatabase.Instrument
Instrument returns the telemetry instrument bound to this connection, or nil when database telemetry is disabled.
func (*Connection) IsCurrent ¶
func (r *Connection) IsCurrent() bool
IsCurrent reports whether this handle still belongs to the cached generation. Facade registries use it to discard handles invalidated through another DB or ORM entry point.
func (*Connection) Name ¶
func (r *Connection) Name() string
Name returns the configured connection name this handle was opened for.
func (*Connection) Purge ¶
func (r *Connection) Purge() error
Purge closes this logical connection's current resources, leaving other aliases untouched. A handle whose generation was already replaced is a no-op, because purging by identity alone would close the pools another Open published in the meantime.
func (*Connection) Reader ¶
func (r *Connection) Reader() *sql.DB
Reader returns the pool compiled reads execute through. A connection configured without replicas reads through its writer, so this always returns a usable pool.
func (*Connection) ServerVersion ¶
func (r *Connection) ServerVersion(ctx context.Context) (string, error)
func (*Connection) SupportsServerVersion ¶
func (r *Connection) SupportsServerVersion() bool
func (*Connection) Writer ¶
func (r *Connection) Writer() *sql.DB
Writer returns the pool writes execute through: inserts, updates, deletes and transactions.
type QueryComponents ¶
type QueryComponents struct {
Grammar contractsquery.Grammar
Processor contractsquery.Processor
Dialect contractsdriver.Dialect
// VersionSource accepts the caller's current context, including after WithContext.
VersionSource func(context.Context) (string, error)
Options contractsdriver.GrammarOptions
}
QueryComponents binds a query compiler and result processor to one connection. Both must be carried together when a builder is rebound to another connection.
func ResolveQueryComponents ¶
func ResolveQueryComponents(dialect contractsdriver.Dialect, options contractsdriver.GrammarOptions) (QueryComponents, error)
ResolveQueryComponents uses the provider before considering a legacy dialect. Database implementations are supplied by their external driver packages.
func (QueryComponents) Validate ¶
func (c QueryComponents) Validate() error
func (QueryComponents) WithContext ¶
func (c QueryComponents) WithContext(ctx context.Context) QueryComponents
WithContext builds a fresh compiler when its version lookup is connection-bound.
Source Files