database

package module
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2023 License: MIT Imports: 17 Imported by: 2

README

Database

GoDoc Go Report Card Coverage Status

Database is wrapper for sqlx with clear interface, retry func and hooks.
Compatible databases: PostgreSQL, Clickhouse, CockroachDB, SQLite.

Install

go get github.com/loghole/database

Usage

package main

import (
	"context"
	"log"

	"github.com/loghole/database"

	_ "github.com/mattn/go-sqlite3"
)

func main() {
	// Make connection config
	cfg := &database.Config{
		Database: ":memory:",
		Type:     database.SQLiteDatabase,
	}

	// Connect to Database with hooks
	db, err := database.New(cfg, database.WithSimplerrHook(), database.WithRetryPolicy(database.RetryPolicy{
		MaxAttempts:       database.DefaultRetryAttempts,
		InitialBackoff:    database.DefaultRetryInitialBackoff,
		MaxBackoff:        database.DefaultRetryMaxBackoff,
		BackoffMultiplier: database.DefaultRetryBackoffMultiplier,
		ErrIsRetryable:    retry,
	}))
	if err != nil {
		panic(err)
	}

	defer db.Close()

	ctx := context.Background()

	// Queries
	db.ExecContext(ctx, "CREATE TABLE t (id INTEGER PRIMARY KEY, text VARCHAR(5))")
	db.ExecContext(ctx, "INSERT into t (id, text) VALUES(?, ?)", 1, "foo")
	// Try 3 times and return error
	if _, err := db.ExecContext(ctx, "INSERT into t (id, text) VALUES(?, ?)", 1, "bar"); err != nil {
		log.Println(err)
	}
}

func retry(err error) bool {
	log.Println(err)

	return true
}

Custom hooks

You can write custom hooks with dbhook and use options database.WithCustomHook(hook)

Documentation

Index

Constants

View Source 
const (
	DefaultRetryAttempts          = 10
	DefaultRetryInitialBackoff    = time.Millisecond
	DefaultRetryMaxBackoff        = time.Millisecond * 100
	DefaultRetryBackoffMultiplier = 1.5
)

Variables

View Source 
var (
	ErrMaxRetryAttempts = errors.New("max retry attempts has been reached")
	ErrInvalidConfig    = errors.New("invalid config")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	Addr         string
	Addrs        []string // for cockroachdb
	User         string
	Database     string
	Type         DBType
	ReadTimeout  string
	WriteTimeout string
	Params       map[string]string

	// Deprecated: use Params for sets certs.
	CertPath string
}

func (*Config) DSN added in v0.3.0 

func (cfg *Config) DSN() string

type DB 

type DB struct {
	DB *sqlx.DB
	// contains filtered or unexported fields
}

func New 

func New(cfg *Config, opts ...Option) (db *DB, err error)

func (*DB) BeginTxx added in v0.6.0 

func (db *DB) BeginTxx(ctx context.Context, opts *sql.TxOptions) (tx *sqlx.Tx, err error)

BeginTxx begins a transaction and returns an *sqlx.Tx instead of an *sql.Tx.

The provided context is used until the transaction is committed or rolled back. If the context is canceled, the sql package will roll back the transaction. Tx.Commit will return an error if the context provided to BeginxContext is canceled.

func (*DB) BindNamed added in v0.6.0 

func (db *DB) BindNamed(query string, arg interface{}) (bound string, arglist []interface{}, err error)

BindNamed binds a query using the DB driver's bindvar type.

func (*DB) Close added in v0.6.0 

func (db *DB) Close() error

Close closes the database and prevents new queries from starting. Close then waits for all queries that have started processing on the server to finish.

It is rare to Close a DB, as the DB handle is meant to be long-lived and shared between many goroutines.

func (*DB) ExecContext added in v0.6.0 

func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (result sql.Result, err error)

ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.

func (*DB) GetContext added in v0.6.0 

func (db *DB) GetContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error

GetContext using this DB. Any placeholder parameters are replaced with supplied args. An error is returned if the result set is empty.

func (*DB) NamedExecContext added in v0.6.0 

func (db *DB) NamedExecContext(ctx context.Context, query string, arg interface{}) (result sql.Result, err error)

NamedExecContext using this DB. Any named placeholder parameters are replaced with fields from arg.

func (*DB) NamedQueryContext added in v0.6.0 

func (db *DB) NamedQueryContext(ctx context.Context, query string, arg interface{}) (rows *sqlx.Rows, err error)

NamedQueryContext using this DB. Any named placeholder parameters are replaced with fields from arg.

func (*DB) PingContext added in v0.10.0 

func (db *DB) PingContext(ctx context.Context) error

PingContext verifies a connection to the database is still alive, establishing a connection if necessary.

func (*DB) PrepareNamedContext added in v0.6.0 

func (db *DB) PrepareNamedContext(ctx context.Context, query string) (stmt *sqlx.NamedStmt, err error)

PrepareNamedContext returns an sqlx.NamedStmt.

func (*DB) PreparexContext added in v0.6.0 

func (db *DB) PreparexContext(ctx context.Context, query string) (stmt *sqlx.Stmt, err error)

PreparexContext returns an sqlx.Stmt instead of a sqlx.Stmt.

func (*DB) QueryxContext added in v0.6.0 

func (db *DB) QueryxContext(ctx context.Context, query string, args ...interface{}) (rows *sqlx.Rows, err error)

QueryxContext queries the database and returns an *sqlx.Rows. Any placeholder parameters are replaced with supplied args.

func (*DB) RunReadTxx added in v0.6.1 

func (db *DB) RunReadTxx(ctx context.Context, fn TransactionFunc) error

RunReadTxx runs transaction callback func with read only `sql.TxOptions`. If an error occurs, the transaction will be retried if it allows `RetryFunc`.

func (*DB) RunTxx 

func (db *DB) RunTxx(ctx context.Context, fn TransactionFunc) error

RunTxx runs transaction callback func with default `sql.TxOptions`. If an error occurs, the transaction will be retried if it allows `RetryFunc`.

Example: 

err := db.RunTxx(ctx, func(ctx context.Context, tx *sqlx.Tx) error {
	var val time.Time

	if err := tx.GetContext(ctx, &val, "SELECT now()"); err != nil {
		return err
	}

	return nil
})
if err != nil {
	return err
}

func (*DB) RunTxxWithOptions added in v0.6.1 

func (db *DB) RunTxxWithOptions(ctx context.Context, opts *sql.TxOptions, fn TransactionFunc) error

RunTxxWithOptions runs transaction callback func with custom `sql.TxOptions`. If an error occurs, the transaction will be retried if it allows `RetryFunc`.

func (*DB) SelectContext added in v0.6.0 

func (db *DB) SelectContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error

SelectContext using this DB. Any placeholder parameters are replaced with supplied args.

func (*DB) SetConnMaxIdleTime added in v0.10.0 

func (db *DB) SetConnMaxIdleTime(d time.Duration)

SetConnMaxIdleTime sets the maximum amount of time a connection may be idle.

Expired connections may be closed lazily before reuse.

If d <= 0, connections are not closed due to a connection's idle time.

func (*DB) SetMaxIdleConns added in v0.10.0 

func (db *DB) SetMaxIdleConns(n int)

SetMaxIdleConns sets the maximum number of connections in the idle connection pool.

If MaxOpenConns is greater than 0 but less than the new MaxIdleConns, then the new MaxIdleConns will be reduced to match the MaxOpenConns limit.

If n <= 0, no idle connections are retained.

The default max idle connections is currently 2. This may change in a future release.

func (*DB) SetMaxOpenConns added in v0.10.0 

func (db *DB) SetMaxOpenConns(n int)

SetMaxOpenConns sets the maximum number of open connections to the database.

If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than MaxIdleConns, then MaxIdleConns will be reduced to match the new MaxOpenConns limit.

If n <= 0, then there is no limit on the number of open connections. The default is 0 (unlimited).

type DBType 

type DBType string
const (
	PGXDatabase        DBType = "pgx"
	PostgresDatabase   DBType = "postgres"
	CockroachDatabase  DBType = "cockroach"
	ClickhouseDatabase DBType = "clickhouse"
	SQLiteDatabase     DBType = "sqlite3"
)

func (DBType) String 

func (d DBType) String() string

type Database added in v0.7.1 

type Database interface {
	// SelectContext using this DB.
	// Any placeholder parameters are replaced with supplied args.
	SelectContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error

	// GetContext using this DB.
	// Any placeholder parameters are replaced with supplied args.
	// An error is returned if the result set is empty.
	GetContext(ctx context.Context, dest interface{}, query string, args ...interface{}) error

	// BindNamed binds a query using the DB driver's bindvar type.
	BindNamed(query string, arg interface{}) (bound string, arglist []interface{}, err error)

	// BeginTxx begins a transaction and returns an *sqlx.Tx instead of an
	// *sql.Tx.
	//
	// The provided context is used until the transaction is committed or rolled
	// back. If the context is canceled, the sql package will roll back the
	// transaction. Tx.Commit will return an error if the context provided to
	// BeginxContext is canceled.
	BeginTxx(ctx context.Context, opts *sql.TxOptions) (*sqlx.Tx, error)

	// ExecContext executes a query without returning any rows.
	// The args are for any placeholder parameters in the query.
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

	// NamedExecContext using this DB.
	// Any named placeholder parameters are replaced with fields from arg.
	NamedExecContext(ctx context.Context, query string, arg interface{}) (sql.Result, error)

	// QueryxContext queries the database and returns an *sqlx.Rows.
	// Any placeholder parameters are replaced with supplied args.
	QueryxContext(ctx context.Context, query string, args ...interface{}) (*sqlx.Rows, error)

	// NamedQueryContext using this DB.
	// Any named placeholder parameters are replaced with fields from arg.
	NamedQueryContext(ctx context.Context, query string, arg interface{}) (*sqlx.Rows, error)

	// PreparexContext returns an sqlx.Stmt instead of a sqlx.Stmt.
	PreparexContext(ctx context.Context, query string) (*sqlx.Stmt, error)

	// PrepareNamedContext returns an sqlx.NamedStmt.
	PrepareNamedContext(ctx context.Context, query string) (*sqlx.NamedStmt, error)

	// RunTxx runs transaction callback func with default `sql.TxOptions`.
	// If an error occurs, the transaction will be retried if it allows `RetryFunc`.
	RunTxx(ctx context.Context, fn TransactionFunc) error

	// RunReadTxx runs transaction callback func with read only `sql.TxOptions`.
	// If an error occurs, the transaction will be retried if it allows `RetryFunc`.
	RunReadTxx(ctx context.Context, fn TransactionFunc) error

	// RunTxxWithOptions runs transaction callback func with custom `sql.TxOptions`.
	// If an error occurs, the transaction will be retried if it allows `RetryFunc`.
	RunTxxWithOptions(ctx context.Context, opts *sql.TxOptions, fn TransactionFunc) error

	// Close closes the database and prevents new queries from starting.
	// Close then waits for all queries that have started processing on the server
	// to finish.
	//
	// It is rare to Close a DB, as the DB handle is meant to be
	// long-lived and shared between many goroutines.
	Close() error
}

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option sets options such as hooks, metrics and retry parameters, etc.

func WithCockroachRetryFunc 

func WithCockroachRetryFunc() Option

func WithCustomHook 

func WithCustomHook(hook dbhook.Hook) Option

func WithDefaultOptions 

func WithDefaultOptions(tracer trace.Tracer) Option

func WithMetricsHook added in v0.5.0 

func WithMetricsHook(collector hooks.MetricCollector) Option

func WithPQRetryFunc added in v0.6.0 

func WithPQRetryFunc(maxAttempts int) Option

func WithPrometheusMetrics added in v0.5.0 

func WithPrometheusMetrics() Option

func WithReconnectHook 

func WithReconnectHook() Option

func WithRetryPolicy added in v0.10.0 

func WithRetryPolicy(retryPolicy RetryPolicy) Option

func WithSimplerrHook 

func WithSimplerrHook() Option

func WithTracingHook 

func WithTracingHook(tracer trace.Tracer) Option

type QueryFunc added in v0.6.0 

type QueryFunc func(ctx context.Context, db *sqlx.DB) error

type RetryFunc 

type RetryFunc func(retryCount int, err error) bool

type RetryPolicy added in v0.10.0 

type RetryPolicy struct {
	// MaxAttempts is the maximum number of attempts.
	//
	// This field is required and must be two or greater.
	MaxAttempts int

	// Exponential backoff parameters. The initial retry attempt will occur at
	// random(0, InitialBackoff). In general, the nth attempt will occur at
	// random(0, min(InitialBackoff*BackoffMultiplier**(n-1), MaxBackoff)).
	//
	// These fields are required and must be greater than zero.
	InitialBackoff    time.Duration
	MaxBackoff        time.Duration
	BackoffMultiplier float64

	// Reports when error is retryable.
	//
	// This field is required and must be non-empty.
	ErrIsRetryable func(err error) bool
}

RetryPolicy defines retry policy for queries.

type TransactionFunc 

type TransactionFunc func(ctx context.Context, tx *sqlx.Tx) error

Source Files

View all Source files

Directories

Path Synopsis
examples
sqlite
internal
dbsqlx
helpers
metrics
query
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.