sqlutil

Documentation

Index

• Variables
• func Batch(cb BatchFunc, batchSize uint) error
• func NamedQueryContext(ctx context.Context, ds DataSource, query string, arg any, ...) error
• func Transact[D any](ctx context.Context, newD func(DataSource) D, ds DataSource, opts *TxOptions, ...) (err error)
• func TransactConn[D any](ctx context.Context, newD func(DataSource) D, ds *sqlx.Conn, opts *TxOptions, ...) (err error)
• func TransactDataSource(ctx context.Context, ds DataSource, opts *TxOptions, ...) error
• func WithoutDefaultTimeout(ctx context.Context) context.Context
• type BatchFunc
• type DataSource
  • func WrapDataSource(db DataSource, l logger.Logger, hs ...QueryHook) DataSource
• type JSON
  • func (j JSON) MarshalJSON() ([]byte, error)
  • func (j *JSON) Scan(value interface{}) error
  • func (j JSON) String() string
  • func (j *JSON) UnmarshalJSON(b []byte) error
  • func (j JSON) Value() (driver.Value, error)
• type LogThresholds
  • func (t *LogThresholds) ContextWithValue(ctx context.Context) context.Context
  • func (t *LogThresholds) FromContextValue(ctx context.Context)
• type QueryHook
  • func MonitorHook(logAll func() bool) QueryHook
  • func TimeoutHook(defaultTimeout func() time.Duration) QueryHook
• type Queryer
• type RowScanner
• type TxOptions

Variables

var PromSQLQueryTime = promauto.NewHistogram(prometheus.HistogramOpts{
	Name:    "sql_query_timeout_percent",
	Help:    "SQL query time as a percentage of timeout.",
	Buckets: []float64{10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120},
})

PromSQLQueryTime is exported temporarily while transitioning the core ORMs.

Functions

func Batch

func Batch(cb BatchFunc, batchSize uint) error

Batch is an iterator for batches of records

func NamedQueryContext

func NamedQueryContext(ctx context.Context, ds DataSource, query string, arg any, fn func(RowScanner) error) error

NamedQueryContext is like sqlx.NamedQueryContext, but it works with any DataSource. fn will be called once for each row.

func Transact

func Transact[D any](ctx context.Context, newD func(DataSource) D, ds DataSource, opts *TxOptions, fn func(tx D) error) (err error)

Transact is a helper for executing transactions with a domain specific type. A typical use looks like:

func (d *MyD) Transact(ctx context.Context, fn func(tx *MyD) error) (err error) {
  return sqlutil.Transact(ctx, d.new, d.db, nil, fn)
}

If you need to combine multiple types in one transaction, you can declare a new type, or use TransactDataSource.

func TransactConn

func TransactConn[D any](ctx context.Context, newD func(DataSource) D, ds *sqlx.Conn, opts *TxOptions, fn func(tx D) error) (err error)

TransactConn is a special case to support *sqlx.Conn, which does not implement the full DataSource interface.

func TransactDataSource

func TransactDataSource(ctx context.Context, ds DataSource, opts *TxOptions, fn func(tx DataSource) error) error

TransactDataSource is a helper for executing transactions. This useful for executing raw SQL queries, or when using more than one type which is not supported by Transact.

func WithoutDefaultTimeout

func WithoutDefaultTimeout(ctx context.Context) context.Context

WithoutDefaultTimeout makes a context.Context exempt from the default timeout normally applied by a TimeoutHook.

Types

type BatchFunc

type BatchFunc func(offset, limit uint) (count uint, err error)

BatchFunc is the function to execute on each batch of records, should return the count of records affected

type DataSource

type DataSource interface {
	sqlx.ExtContext
	sqlx.PreparerContext
	GetContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error
	SelectContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error
	PrepareNamedContext(ctx context.Context, query string) (*sqlx.NamedStmt, error)
	NamedExecContext(ctx context.Context, query string, arg interface{}) (sql.Result, error)
}

DataSource is implemented by *sqlx.DB & *sqlx.Tx.

func WrapDataSource

func WrapDataSource(db DataSource, l logger.Logger, hs ...QueryHook) DataSource

WrapDataSource returns a new DataSource that calls each QueryHook in the provided order. If db implements sqlx.BeginTxx, then the returned DataSource will also.

type JSON

type JSON json.RawMessage

JSON defined JSON data type, need to implements driver.Valuer, sql.Scanner interface

func (JSON) MarshalJSON

func (j JSON) MarshalJSON() ([]byte, error)

MarshalJSON to output non base64 encoded []byte

func (*JSON) Scan

func (j *JSON) Scan(value interface{}) error

Scan scan value into Jsonb, implements sql.Scanner interface

func (JSON) String

func (j JSON) String() string

func (*JSON) UnmarshalJSON

func (j *JSON) UnmarshalJSON(b []byte) error

UnmarshalJSON to deserialize []byte

func (JSON) Value

func (j JSON) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface

type LogThresholds

type LogThresholds struct {
	Warn  func(timeout time.Duration) (threshold time.Duration)
	Error func(timeout time.Duration) (threshold time.Duration)
}

LogThresholds holds funcs for computing thresholds for timeout usage.

func (*LogThresholds) ContextWithValue

func (t *LogThresholds) ContextWithValue(ctx context.Context) context.Context

func (*LogThresholds) FromContextValue

func (t *LogThresholds) FromContextValue(ctx context.Context)

FromContextValue sets LogThresholds from the context value, if one is present. nil fields are set to default functions. 10% for Warn, and 20% for Error.

type QueryHook

type QueryHook func(ctx context.Context, lggr logger.Logger, do func(context.Context) error, query string, args ...any) error

QueryHook is a func that is executed for each query, providing an opportunity to measure, log, inspect/modify errors, etc. The do func *must* be called. Logs emitted through the provided logger.Logger will have the caller's line info.

See MonitorHook and TimeoutHook for examples.

func MonitorHook

func MonitorHook(logAll func() bool) QueryHook

MonitorHook returns a QueryHook that measures the timing of each query and logs about slow queries at increasing levels of severity. When logAll returns true, every query and error will be logged.

func TimeoutHook

func TimeoutHook(defaultTimeout func() time.Duration) QueryHook

TimeoutHook returns a QueryHook which adds the defaultTimeout to each context.Context, unless WithoutDefaultTimeout has been applied to bypass intentionally.

type Queryer

type Queryer = DataSource

type RowScanner

type RowScanner interface {
	Scan(dest ...any) error
	SliceScan() ([]interface{}, error)
	MapScan(dest map[string]interface{}) error
	StructScan(dest interface{}) error
}

type TxOptions

type TxOptions struct {
	sql.TxOptions
	OnPanic func(recovered any, rollbackErr error)
}