tagsql

Documentation

Overview

Package tagsql implements a tagged wrapper for databases.

This package also handles hides context cancellation from database drivers that don't support it.

Index

• Constants
• type Conn
• type ContextSupport
  • func DetectContextSupport(db *sql.DB) (ContextSupport, error)
  • func (v ContextSupport) Basic() bool
  • func (v ContextSupport) Transactions() bool
• type DB
  • func AllowContext(db *sql.DB) DB
  • func Open(ctx context.Context, driverName, dataSourceName string) (DB, error)
  • func WithoutContext(db *sql.DB) DB
  • func Wrap(db *sql.DB) DB
• type Rows
• type Stmt
• type Tx

Constants

const (

	// CockroachName is the name when tagsql wraps a Cockroach DB connection.
	CockroachName string = "cockroach"

	// PostgresName is the name when tagsql wraps a Cockroach DB connection.
	PostgresName string = "postgres"

	// SpannerName is the name when tagsql wraps a Cockroach DB connection.
	SpannerName string = "spanner"
)

Types

type Conn

type Conn interface {
	BeginTx(ctx context.Context, txOptions *sql.TxOptions) (Tx, error)
	Close() error
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	PingContext(ctx context.Context) error
	PrepareContext(ctx context.Context, query string) (Stmt, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row
	Raw(ctx context.Context, f func(driverConn interface{}) error) (err error)
}

Conn is an interface for *sql.Conn-like connections.

type ContextSupport

type ContextSupport byte

ContextSupport returns the level of context support a driver has.

const (
	SupportBasic        ContextSupport = 1 << 0
	SupportTransactions ContextSupport = 1 << 1

	SupportNone ContextSupport = 0
	SupportAll  ContextSupport = SupportBasic | SupportTransactions
)

Constants for defining context level support.

func DetectContextSupport

func DetectContextSupport(db *sql.DB) (ContextSupport, error)

DetectContextSupport detects *sql.DB driver without importing the specific packages.

func (ContextSupport) Basic

func (v ContextSupport) Basic() bool

Basic returns true when driver supports basic contexts.

func (ContextSupport) Transactions

func (v ContextSupport) Transactions() bool

Transactions returns true when driver supports contexts inside transactions.

type DB

type DB interface {
	Name() string

	// To be deprecated, the following take ctx as argument,
	// however do not pass it forward to the underlying database.
	Begin(ctx context.Context) (Tx, error)
	Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	Ping(ctx context.Context) error
	Prepare(ctx context.Context, query string) (Stmt, error)
	Query(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRow(ctx context.Context, query string, args ...interface{}) *sql.Row

	BeginTx(ctx context.Context, txOptions *sql.TxOptions) (Tx, error)
	Conn(ctx context.Context) (Conn, error)
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	PingContext(ctx context.Context) error
	PrepareContext(ctx context.Context, query string) (Stmt, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

	Close() error

	SetConnMaxLifetime(d time.Duration)
	SetMaxIdleConns(n int)
	SetMaxOpenConns(n int)
	Stats() sql.DBStats
}

DB implements a wrapper for *sql.DB-like database.

The wrapper adds tracing to all calls. It also adds context handling compatibility for different databases.

func AllowContext

func AllowContext(db *sql.DB) DB

AllowContext turns a *sql.DB into a DB which uses context calls.

func Open

func Open(ctx context.Context, driverName, dataSourceName string) (DB, error)

Open opens *sql.DB and wraps the implementation with tagging.

func WithoutContext

func WithoutContext(db *sql.DB) DB

WithoutContext turns a *sql.DB into a DB-matching that redirects context calls to regular calls.

func Wrap

func Wrap(db *sql.DB) DB

Wrap turns a *sql.DB into a DB-matching interface.

type Rows

type Rows interface {
	Close() error
	ColumnTypes() ([]*sql.ColumnType, error)
	Columns() ([]string, error)
	Err() error
	Next() bool
	NextResultSet() bool
	Scan(dest ...interface{}) error
}

Rows implements a wrapper for *sql.Rows.

type Stmt

type Stmt interface {
	// Exec and other methods take a context for tracing
	// purposes, but do not pass the context to the underlying database query.
	Exec(ctx context.Context, args ...interface{}) (sql.Result, error)
	Query(ctx context.Context, args ...interface{}) (Rows, error)
	QueryRow(ctx context.Context, args ...interface{}) *sql.Row

	// ExecContext and other Context methods take a context for tracing and also
	// pass the context to the underlying database, if this tagsql instance is
	// configured to do so. (By default, lib/pq does not ever, and
	// mattn/go-sqlite3 does not for transactions).
	ExecContext(ctx context.Context, args ...interface{}) (sql.Result, error)
	QueryContext(ctx context.Context, args ...interface{}) (Rows, error)
	QueryRowContext(ctx context.Context, args ...interface{}) *sql.Row

	Close() error
}

Stmt is an interface for *sql.Stmt.

type Tx

type Tx interface {
	// Exec and other methods take a context for tracing
	// purposes, but do not pass the context to the underlying database query
	Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	Prepare(ctx context.Context, query string) (Stmt, error)
	Query(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRow(ctx context.Context, query string, args ...interface{}) *sql.Row

	// ExecContext and other Context methods take a context for tracing and also
	// pass the context to the underlying database, if this tagsql instance is
	// configured to do so. (By default, lib/pq does not ever, and
	// mattn/go-sqlite3 does not for transactions).
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	PrepareContext(ctx context.Context, query string) (Stmt, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

	Commit() error
	Rollback() error
}

Tx is an interface for *sql.Tx-like transactions.