Documentation
¶
Overview ¶
Package wrapper provides driver-agnostic wrappers around database/sql.Stmt and database/sql.Tx that implement the types.Statement and types.Tx interfaces. Extracted from byte-identical code in database/postgresql/ and database/oracle/ so a future vendor (or a behavior change to the wrapping logic) lives in one place.
The wrapped sql.Stmt/sql.Tx values are stored unexported. Callers should construct via NewStatement/NewTransaction; both vendor packages re-export the wrapper types via type aliases to preserve their public API.
Index ¶
- func AppendPoolFields(ev logger.LogEvent, cfg *config.DatabaseConfig) logger.LogEvent
- type Connection
- func (c *Connection) Begin(ctx context.Context) (types.Tx, error)
- func (c *Connection) BeginTx(ctx context.Context, opts *sql.TxOptions) (types.Tx, error)
- func (c *Connection) Close() error
- func (c *Connection) Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (c *Connection) Health(ctx context.Context) error
- func (c *Connection) OpenSession(ctx context.Context, vendor string) (types.Session, error)
- func (c *Connection) Prepare(ctx context.Context, query string) (types.Statement, error)
- func (c *Connection) Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
- func (c *Connection) QueryRow(ctx context.Context, query string, args ...any) types.Row
- func (c *Connection) Stats() (map[string]any, error)
- type Session
- func (s *Session) Begin(ctx context.Context) (types.Tx, error)
- func (s *Session) BeginTx(ctx context.Context, opts *sql.TxOptions) (types.Tx, error)
- func (s *Session) Close() error
- func (s *Session) DatabaseType() string
- func (s *Session) Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (s *Session) Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
- func (s *Session) QueryRow(ctx context.Context, query string, args ...any) types.Row
- type Statement
- type Transaction
- func (t *Transaction) Commit(_ context.Context) error
- func (t *Transaction) Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (t *Transaction) Prepare(ctx context.Context, query string) (types.Statement, error)
- func (t *Transaction) Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
- func (t *Transaction) QueryRow(ctx context.Context, query string, args ...any) types.Row
- func (t *Transaction) Rollback(_ context.Context) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendPoolFields ¶ added in v0.41.0
AppendPoolFields adds the effective connection-pool settings to a log event so operators can confirm what the pool actually uses after defaulting. Shared by the PostgreSQL and Oracle connection layers so the logged field set cannot drift between vendors.
Types ¶
type Connection ¶
type Connection struct {
DB *sql.DB
Config *config.DatabaseConfig
Logger logger.Logger
MetricsCleanup func()
Name string // vendor display name, e.g. "PostgreSQL", "Oracle"
}
Connection holds the byte-identical fields and delegation methods that previously lived in both postgresql.Connection and oracle.Connection. Vendor packages embed this struct (typically by pointer) and add only the vendor-specific bits (DatabaseType / MigrationTable / CreateMigrationTable DDL / dialer plumbing).
Fields are exported so vendor packages can construct via struct literal in their NewConnection, and so the metrics-registration callback can flip MetricsCleanup after wiring it up. The Name field flows into Close()'s "Closing X database connection" log message — the only previously vendor-specific bit in those nine methods.
func (*Connection) Close ¶
func (c *Connection) Close() error
Close closes the underlying *sql.DB, unregisters the metrics callback (if any), and logs the shutdown. The Name field is used to render the vendor name into the log message.
func (*Connection) Health ¶
func (c *Connection) Health(ctx context.Context) error
Health checks database connectivity with a 5s timeout. The caller's context is honored if it has a shorter deadline.
func (*Connection) OpenSession ¶ added in v0.65.0
OpenSession acquires a dedicated physical connection from the pool via (*sql.DB).Conn, pinned for the caller until Close.
func (*Connection) Stats ¶
func (c *Connection) Stats() (map[string]any, error)
Stats returns database connection statistics in a map suitable for logging or metrics tracking. When Config is non-nil, the configured idle-connection cap is included for visibility (Go's sql.DB treats the idle setting as a cap, not a floor — it does not pre-warm or maintain a minimum idle count).
type Session ¶ added in v0.65.0
type Session struct {
// contains filtered or unexported fields
}
Session wraps a *sql.Conn pinned to a single physical database connection, so every statement runs on the same backend. See types.Session for the error and concurrency contract.
func (*Session) Begin ¶ added in v0.65.0
Begin starts a transaction on the pinned connection with default options.
func (*Session) BeginTx ¶ added in v0.65.0
BeginTx starts a transaction on the pinned connection with explicit options.
func (*Session) Close ¶ added in v0.65.0
Close releases the pinned physical connection back to the pool. A connection already shown dead is discarded instead: (*sql.Conn).Close releases with a nil error, which would return it to the pool, while Raw releasing with driver.ErrBadConn makes database/sql drop it.
func (*Session) DatabaseType ¶ added in v0.65.0
DatabaseType returns the vendor identifier this Session was opened with.
type Statement ¶
type Statement struct {
// contains filtered or unexported fields
}
Statement wraps sql.Stmt to implement types.Statement.
func NewStatement ¶
NewStatement wraps a sql.Stmt as a types.Statement implementation.
type Transaction ¶
type Transaction struct {
// contains filtered or unexported fields
}
Transaction wraps sql.Tx to implement types.Tx.
func NewTransaction ¶
func NewTransaction(tx *sql.Tx) *Transaction
NewTransaction wraps a sql.Tx as a types.Tx implementation.
func (*Transaction) Commit ¶
func (t *Transaction) Commit(_ context.Context) error
Commit commits the transaction. Note: database/sql's Tx.Commit doesn't accept context; it's atomic and non-cancellable. The context parameter maintains interface consistency for databases that support cancellable commit (if a future vendor adds one).
Source Files