driver

package
v6.4.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrSessionUnsupported = errors.New("driver does not support dedicated prepared sessions")
	ErrSessionClosed      = errors.New("session is closed")
	ErrSessionInvalidated = errors.New("session connection was lost; close the session and prepare again")
	ErrSessionCapacity    = errors.New("dedicated sessions exceed connection pool capacity")
	ErrSessionBusy        = errors.New("session has an open result cursor")
	ErrSessionTransaction = errors.New("session has an active transaction; use the transaction handle")
	ErrSessionMismatch    = errors.New("prepared statement belongs to another session")
	ErrPreparedClosed     = errors.New("prepared statement is closed")
	ErrSessionIsolation   = errors.New("dedicated session transactions require database isolation")
	ErrTransactionClosed  = errors.New("transaction already finalized")
)
View Source
var ErrInsertMethodNotSupported = errors.New("driver: insert method not supported")

ErrInsertMethodNotSupported is returned by a driver's Insert when the request's method is not one the driver serves (see InsertCapabilities).

View Source
var ErrInsertMethodUnsupported = errors.New("insert method not supported by driver")

ErrInsertMethodUnsupported is returned when a resolved insert method is not served by the selected driver.

View Source
var ErrNilInsertRequest = errors.New("driver: nil insert request")

ErrNilInsertRequest is returned when a driver's Insert receives a nil request pointer.

View Source
var ErrNilInsertSource = errors.New("driver: nil insert source")

ErrNilInsertSource is returned when an InsertRequest carries no source.

View Source
var ErrNoRegisteredDriver = errors.New("no registered driver")
View Source
var ErrTransactionIsolation = errors.New("unsupported transaction isolation")
View Source
var ErrUnknownInsertMethod = errors.New("unknown insert method")

ErrUnknownInsertMethod is returned by ParseInsertMethod for an unrecognized method string.

Functions

func DefaultIsolation added in v6.3.3

func DefaultIsolation(cfg *config.DriverConfig) (config.TxIsolationLevel, error)

func FoldBegin added in v6.3.3

func FoldBegin(cfg *config.DriverConfig) bool

func IsolationSQL added in v6.3.3

func IsolationSQL(level config.TxIsolationLevel) (string, error)

func JoinErrors

func JoinErrors(errs ...error) error

JoinErrors combines distinct error causes while preserving errors.Is behavior.

func ParseIsolation added in v6.3.3

func ParseIsolation(value string) (config.TxIsolationLevel, error)

func RegisterDriver

func RegisterDriver(
	driverType config.DriverType,
	constructor driverConstructor,
)

func SupportsInsertMethod

func SupportsInsertMethod(driverType config.DriverType, method InsertMethod) bool

SupportsInsertMethod reports whether driverType's implementation serves method.

func ValidateInsert

func ValidateInsert(req *InsertRequest) error

ValidateInsert checks the request shape shared by every driver's Insert entry. A nil request, a nil source, or a zero-column schema are rejected before driver-specific dispatch; per-driver method capability is validated in each driver.

Types

type Driver

type Driver interface {
	// Insert runs a typed [InsertRequest] through the driver, streaming
	// rows from a workload-authored [gen.BatchSource] into the database.
	// Generation after cursor preparation allocates nothing; driver-side
	// encoding and materialization may.
	Insert(ctx context.Context, req *InsertRequest) (*stats.Query, error)
	RunQuery(ctx context.Context, sql string, args map[string]any) (*QueryResult, error)
	Begin(ctx context.Context, isolation config.TxIsolationLevel) (Tx, error)
	ClassifyError(err error) ErrorFacts
	Teardown(ctx context.Context) error
}

func Dispatch

func Dispatch(
	ctx context.Context,
	opts Options,
) (Driver, error)

type ErrorFacts

type ErrorFacts struct {
	Kind                ErrorKind
	Backoff             bool
	RequiresIdempotency bool
}

ErrorFacts are backend-neutral properties used by workload error policy.

func DefaultErrorFacts

func DefaultErrorFacts(err error) ErrorFacts

DefaultErrorFacts classifies errors shared by every driver. Unknown errors remain explicit so policy defaults fail closed instead of retrying them.

type ErrorKind

type ErrorKind string

ErrorKind describes a database-independent property of a driver error.

const (
	ErrorKindUniqueViolation     ErrorKind = "unique_violation"
	ErrorKindConstraintViolation ErrorKind = "constraint_violation"
	ErrorKindUnknown             ErrorKind = "unknown"
	ErrorKindSerialization       ErrorKind = "serialization"
	ErrorKindDeadlock            ErrorKind = "deadlock"
	ErrorKindLockTimeout         ErrorKind = "lock_timeout"
	ErrorKindTransient           ErrorKind = "transient"
	ErrorKindUnsupported         ErrorKind = "unsupported"
	ErrorKindCanceled            ErrorKind = "canceled"
	ErrorKindTimeout             ErrorKind = "timeout"
)

type InsertCapability

type InsertCapability struct {
	Type          config.DriverType
	InsertMethods []InsertMethod
}

InsertCapability pairs a driver type with the insert methods its implementation serves.

func InsertCapabilities

func InsertCapabilities() []InsertCapability

InsertCapabilities returns the driver→insert-method matrix ordered by driver enum value. Method lists follow enum value order too, so output is deterministic for machine consumers.

type InsertMethod

type InsertMethod int

InsertMethod names a row-insertion strategy. The typed Driver.Insert path uses this Go-native enum; a driver advertises the methods it serves via InsertCapabilities.

The method describes how a driver lands rows, not how a generator stores them: NATIVE is a driver-specific bulk primitive (COPY, BulkUpsert, …), PLAIN_BULK is a multi-row INSERT, PLAIN_QUERY is one INSERT per row, and COLUMNAR is a single-array-per-column protocol (e.g. unnest).

const (
	InsertPlainQuery InsertMethod = iota + 1
	InsertPlainBulk
	InsertColumnar
	InsertNative
)

func ParseInsertMethod

func ParseInsertMethod(s string) (InsertMethod, error)

ParseInsertMethod resolves an authoring string to a driver InsertMethod. The empty string selects plain_query, matching the legacy default.

func ResolveInsertMethod

func ResolveInsertMethod(driverType config.DriverType, s string) (InsertMethod, error)

ResolveInsertMethod parses an authoring string and rejects methods the selected driver does not serve, so an invalid or unsupported value fails before a run starts loading.

func (InsertMethod) String

func (m InsertMethod) String() string

String returns the stable, lowercase method name used in CLI strings and probe output ("plain_query", "plain_bulk", "columnar", "native").

type InsertRequest

type InsertRequest struct {
	Table   string
	Method  InsertMethod
	Workers int
	Source  gen.BatchSource
}

InsertRequest carries a driver-owned InsertMethod, a worker count, and a gen.BatchSource whose prepared partitions fill reusable typed batches. Workloads hand their source straight to the driver, avoiding intermediate row representations.

Source, Method, and Workers are the driver's full input; the table name is carried separately because generation is table-agnostic.

type Options

type Options struct {
	// DialFunc lets the runner observe or customize driver network dials.
	DialFunc func(ctx context.Context, network, addr string) (net.Conn, error)
	Logger   *zap.Logger
	Config   *config.DriverConfig

	// QueryTimeout bounds each statement; <= 0 disables the deadline.
	QueryTimeout time.Duration
}

type PoolCapacity added in v6.3.0

type PoolCapacity interface {
	// PoolMaxConns returns the effective connection cap; zero means unlimited or unknown.
	PoolMaxConns() int
}

PoolCapacity is optional so drivers without connection pools need no stub.

type PoolSnapshot added in v6.4.0

type PoolSnapshot struct {
	Backend string
	Scope   string
	Reason  string
	// Unsupported pools must not look like supported pools with no contention.
	Supported bool
	// Zero means unlimited; a negative limit means unknown.
	MaxConnections int64
	Open           int64
	InUse          int64
	Idle           int64
	WaitCount      int64
	WaitDuration   time.Duration
	Canceled       int64
}

type PoolStatistics added in v6.4.0

type PoolStatistics interface {
	PoolStats() PoolSnapshot
}

PoolStatistics is optional because some SDKs hide their pools or use no pool.

type Prepared added in v6.3.0

type Prepared interface {
	RunQuery(ctx context.Context, args map[string]any) (*QueryResult, error)
	Close(ctx context.Context) error
}

type QueryResult

type QueryResult struct {
	Stats *stats.Query
	Rows  Rows
}

type RoutineError added in v6.3.3

type RoutineError struct {
	Cause             error
	RollbackConfirmed bool
	Ambiguous         bool
}

RoutineError distinguishes a server-confirmed rollback from a lost commit acknowledgement.

func (*RoutineError) Error added in v6.3.3

func (e *RoutineError) Error() string

func (*RoutineError) Unwrap added in v6.3.3

func (e *RoutineError) Unwrap() error

type RoutineExecutor added in v6.3.3

type RoutineExecutor interface {
	RunRoutine(ctx context.Context, isolation config.TxIsolationLevel,
		query string, args map[string]any) (*QueryResult, error)
}

RoutineExecutor executes one self-contained atomic routine invocation.

type Rows

type Rows interface {
	Columns() []string
	Next() bool
	Values() []any
	ReadAll(limit int) [][]any
	Err() error
	Close() error
}

Rows provides cursor-style iteration over query result rows. Automatically closes when Next() returns false (exhaustion or error).

type Session added in v6.3.0

type Session interface {
	RunQuery(ctx context.Context, sql string, args map[string]any) (*QueryResult, error)
	Prepare(ctx context.Context, name, sql string) (Prepared, error)
	Begin(ctx context.Context, isolation config.TxIsolationLevel) (SessionTx, error)
	Close(ctx context.Context) error
}

type SessionProvider added in v6.3.0

type SessionProvider interface {
	OpenSession(ctx context.Context) (Session, error)
	SessionCapacity() int
}

SessionProvider is optional so pooled drivers need not emulate session affinity.

type SessionTx added in v6.3.0

type SessionTx interface {
	Tx
	RunPrepared(ctx context.Context, statement Prepared, args map[string]any) (*QueryResult, error)
}

type Tx

type Tx interface {
	RunQuery(ctx context.Context, sql string, args map[string]any) (*QueryResult, error)
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
	Isolation() config.TxIsolationLevel
}

Directories

Path Synopsis
Package common hosts driver-agnostic building blocks shared by every Stroppy database driver.
Package common hosts driver-agnostic building blocks shared by every Stroppy database driver.
Package csv implements an ephemeral Stroppy driver that writes generator output to CSV files on the local filesystem instead of a database.
Package csv implements an ephemeral Stroppy driver that writes generator output to CSV files on the local filesystem instead of a database.
Package insertprogress provides driver-agnostic insert operation progress tracking.
Package insertprogress provides driver-agnostic insert operation progress tracking.
Package noop provides a no-op database driver that discards all operations without performing any I/O. It is intended for benchmarking stroppy's own framework overhead in isolation from actual database latency.
Package noop provides a no-op database driver that discards all operations without performing any I/O. It is intended for benchmarking stroppy's own framework overhead in isolation from actual database latency.
Package recording implements a database-free driver that records operations.
Package recording implements a database-free driver that records operations.

Jump to

Keyboard shortcuts

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