sqldriver

package
v6.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrMissedArgument = errors.New("missed arguments present")
	ErrExtraArgument  = errors.New("extra arguments provided")
)
View Source
var ErrDBConnectionTimeout = errors.New("database connection timeout")

ErrDBConnectionTimeout is returned when database connection times out.

View Source
var ErrEmptyColumnOrder = errors.New("sqldriver: source reports zero columns")

ErrEmptyColumnOrder is returned when the source reports zero columns; an INSERT without columns is not a valid target for the bulk path.

View Source
var ErrUnsupportedInsertMethod = errors.New("sqldriver: unsupported insert method")

ErrUnsupportedInsertMethod is returned when the shared SQL helper receives a driver-specific method (currently NATIVE). Drivers handle that method before delegating here.

Functions

func ApplySQLConfig

func ApplySQLConfig(db *sql.DB, sqlCfg *config.SQLConfig) error

ApplySQLConfig applies SQL pool configuration to a *sql.DB. Returns an error if any duration string is malformed.

func IsolationToSQL

func IsolationToSQL(level config.TxIsolationLevel) sql.IsolationLevel

IsolationToSQL maps the isolated level to database/sql isolation level.

func NewRows

func NewRows(sqlRows *sql.Rows) driver.Rows

func PoolSnapshot added in v6.4.0

func PoolSnapshot(db *sql.DB, scope string) driver.PoolSnapshot

func ProcessArgs

func ProcessArgs(
	dialect queries.Dialect, sqlStr string, args map[string]any,
) (newSQL string, argsArr []any, err error)

ProcessArgs takes sql which contains ":arg" marks and args map "arg" -> value. It returns sql where all marks are replaced with dialect-specific placeholders, and an array of any containing the arguments in the right order. When dialect.Deduplicate() is true, repeated named parameters share a single positional placeholder (e.g. pgx's $1 back-references).

The regex + string-building parse phase is cached per (dialect, sqlStr) pair so that repeated calls with the same template pay only a map lookup.

func ProcessArgsInto added in v6.4.0

func ProcessArgsInto(
	dialect queries.Dialect, sqlStr string, args map[string]any, destination []any,
) (newSQL string, argsArr []any, err error)

ProcessArgsInto reuses caller-owned storage. The caller must not refill it until the previous query has finished consuming all arguments and rows.

func ReferencedArgs added in v6.4.0

func ReferencedArgs(sqlStr string, args map[string]any) map[string]any

ReferencedArgs uses the same parameter-token rules as ProcessArgs so callers can adapt shared parameter sets without hiding missing bindings.

func RunBulkInsert

func RunBulkInsert[T any](
	ctx context.Context,
	db ExecContext[T],
	table string,
	src source.RowSource,
	dialect queries.Dialect,
	batchSize int,
	timeout time.Duration,
) error

func RunQuery

func RunQuery[R any](
	ctx context.Context,
	db QueryContext[R],
	wrapRows func(R) driver.Rows,
	dialect queries.Dialect,
	lg *zap.Logger,
	sqlStr string,
	args map[string]any,
	timeout time.Duration,
) (*driver.QueryResult, error)

RunQuery executes sql with named :arg placeholders and returns rows cursor. timeout > 0 bounds the single statement: every call derives a child context so the deadline applies per statement rather than to an entire query suite, and a dialect-provided server-side hint (MySQL MAX_EXECUTION_TIME) bounds the backend where client-side cancellation alone would not keep the pooled connection reusable.

func StatementTimeout

func StatementTimeout(ctx context.Context, timeout time.Duration) (context.Context, context.CancelFunc)

StatementTimeout returns a child context bounded by timeout, or ctx unchanged (with a no-op cancel) when timeout is non-positive. Callers release the child once the statement and any result-row iteration complete.

func Teardown

func Teardown(_ context.Context, db io.Closer) error

Teardown closes the database connection pool.

func WaitForDB

func WaitForDB(
	ctx context.Context,
	lg *zap.Logger,
	pingable interface {
		Ping(ctx context.Context) error
	},
	timeout time.Duration,
) error

WaitForDB retries pinging the database until success or timeout.

Types

type ConnOnlyTx

type ConnOnlyTx[R any] struct {
	// contains filtered or unexported fields
}

ConnOnlyTx wraps a bare connection (no SQL transaction) as a driver.Tx. Commit and Rollback both call close to release the connection.

func NewConnOnlyTx

func NewConnOnlyTx[R any](
	conn QueryContext[R],
	wrapRows func(R) driver.Rows,
	dialect queries.Dialect,
	logger *zap.Logger,
	timeout time.Duration,
	closeFunc func() error,
) *ConnOnlyTx[R]

func (*ConnOnlyTx[R]) Commit

func (t *ConnOnlyTx[R]) Commit(_ context.Context) error

func (*ConnOnlyTx[R]) Isolation

func (t *ConnOnlyTx[R]) Isolation() config.TxIsolationLevel

func (*ConnOnlyTx[R]) Rollback

func (t *ConnOnlyTx[R]) Rollback(_ context.Context) error

func (*ConnOnlyTx[R]) RunQuery

func (t *ConnOnlyTx[R]) RunQuery(
	ctx context.Context,
	sqlStr string,
	args map[string]any,
) (*driver.QueryResult, error)

type DBPinger

type DBPinger struct {
	DB *sql.DB
}

DBPinger adapts *sql.DB to the Ping interface expected by WaitForDB.

func (*DBPinger) Ping

func (p *DBPinger) Ping(ctx context.Context) error

type ExecContext

type ExecContext[T any] interface {
	ExecContext(ctx context.Context, query string, args ...any) (T, error)
}

ExecContext is accepted by InsertPlainQuery and InsertPlainBulk.

type PreparedQuery added in v6.3.0

type PreparedQuery[R any] interface {
	QueryContext(ctx context.Context, args ...any) (R, error)
	Close(ctx context.Context) error
}

type QueryContext

type QueryContext[R any] interface {
	QueryContext(ctx context.Context, query string, args ...any) (R, error)
}

QueryContext is accepted by RunQuery.

type Rows

type Rows struct {
	// contains filtered or unexported fields
}

func (*Rows) Close

func (r *Rows) Close() error

func (*Rows) Columns

func (r *Rows) Columns() []string

func (*Rows) Err

func (r *Rows) Err() error

func (*Rows) Next

func (r *Rows) Next() bool

func (*Rows) ReadAll

func (r *Rows) ReadAll(limit int) [][]any

ReadAll reads up to limit rows and closes the cursor. limit <= 0 means no limit.

func (*Rows) Values

func (r *Rows) Values() []any

type SQLTxAdapter

type SQLTxAdapter struct{ *sql.Tx }

SQLTxAdapter adapts *sql.Tx to TxConn[*sql.Rows]. *sql.Tx already satisfies QueryContext[*sql.Rows]; this adapter adds context-aware Commit/Rollback wrappers (sql.Tx has no-context variants).

func (*SQLTxAdapter) Commit

func (a *SQLTxAdapter) Commit(_ context.Context) error

func (*SQLTxAdapter) Rollback

func (a *SQLTxAdapter) Rollback(_ context.Context) error

type Session added in v6.3.0

type Session[R any] struct {
	// contains filtered or unexported fields
}

func NewSession added in v6.3.0

func NewSession[R any](conn SessionConnection[R], wrapRows func(R) driver.Rows,
	dialect queries.Dialect, logger *zap.Logger, timeout time.Duration,
) *Session[R]

func (*Session[R]) Begin added in v6.3.0

func (s *Session[R]) Begin(ctx context.Context, isolation config.TxIsolationLevel) (driver.SessionTx, error)

func (*Session[R]) Close added in v6.3.0

func (s *Session[R]) Close(ctx context.Context) error

func (*Session[R]) Prepare added in v6.3.0

func (s *Session[R]) Prepare(ctx context.Context, _, sql string) (driver.Prepared, error)

func (*Session[R]) RunQuery added in v6.3.0

func (s *Session[R]) RunQuery(ctx context.Context, sql string, args map[string]any) (*driver.QueryResult, error)

type SessionConnection added in v6.3.0

type SessionConnection[R any] interface {
	QueryContext[R]
	PrepareContext(ctx context.Context, sql string) (PreparedQuery[R], error)
	Begin(ctx context.Context, isolation config.TxIsolationLevel) (TxConn[R], error)
	Close(ctx context.Context) error
	Valid() bool
}

type Tx

type Tx[R any] struct {
	// contains filtered or unexported fields
}

Tx wraps a TxConn and implements driver.Tx.

func NewTx

func NewTx[R any](
	conn TxConn[R],
	wrapRows func(R) driver.Rows,
	isolation config.TxIsolationLevel,
	dialect queries.Dialect,
	logger *zap.Logger,
	timeout time.Duration,
) *Tx[R]

func (*Tx[R]) Commit

func (t *Tx[R]) Commit(ctx context.Context) error

func (*Tx[R]) Isolation

func (t *Tx[R]) Isolation() config.TxIsolationLevel

func (*Tx[R]) Rollback

func (t *Tx[R]) Rollback(ctx context.Context) error

func (*Tx[R]) RunQuery

func (t *Tx[R]) RunQuery(
	ctx context.Context,
	sqlStr string,
	args map[string]any,
) (*driver.QueryResult, error)

type TxConn

type TxConn[R any] interface {
	QueryContext[R]
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
}

TxConn is the minimal interface that an underlying transaction must satisfy. It combines QueryContext with context-aware Commit/Rollback.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL