dbkit

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2024 License: MIT Imports: 12 Imported by: 0

README

Toolkit for working with SQL databases in Go

Structure

/

Package dbkit provides helpers for working with different SQL databases (MySQL, PostgreSQL, SQLite and MSSQL).

/distrlock

Package distrlock contains DML (distributed lock manager) implementation (now DMLs based on MySQL and PostgreSQL are supported). Now only manager that uses SQL database (PostgreSQL and MySQL are currently supported) is available. Other implementations (for example, based on Redis) will probably be implemented in the future.

/migrate

Package migrate provides functionality for applying database migrations.

/mssql

Package mssql provides helpers for working with MSSQL. Should be imported explicitly. To register mssql as retryable func use side effect import like so:

import _ "github.com/acronis/go-dbkit/mssql"
/mysql

Package mysql provides helpers for working with MySQL. Should be imported explicitly. To register mysql as retryable func use side effect import like so:

import _ "github.com/acronis/go-dbkit/mysql"
/pgx

Package pgx provides helpers for working with Postgres via jackc/pgx driver. Should be imported explicitly. To register postgres as retryable func use side effect import like so:

import _ "github.com/acronis/go-dbkit/pgx"
/postgres

Package postgres provides helpers for working with Postgres via lib/pq driver. Should be imported explicitly. To register postgres as retryable func use side effect import like so:

import _ "github.com/acronis/go-dbkit/postgres"
/sqlite

Package sqlite provides helpers for working with SQLite. Should be imported explicitly. To register sqlite as retryable func use side effect import like so:

import _ "github.com/acronis/go-dbkit/sqlite"
/dbrutil

Package dbrutil provides utilities and helpers for dbr query builder.

/goquutil

Package goquutil provides auxiliary routines for working with goqu query builder.

Examples

Open database connection using the dbrutil package
func main() {
	// Create a new database configuration
	cfg := &db.Config{
		Driver:   db.DialectMySQL,
		Host:     "localhost",
		Port:     3306,
		Username: "your-username",
		Password: "your-password",
		Database: "your-database",
	}

	// Open a connection to the database
	conn, err := dbrutil.Open(cfg, true, nil)
	if err != nil {
		fmt.Println("Failed to open database connection:", err)
		return
	}
	defer conn.Close()

	// Create a new transaction runner
	runner := dbrutil.NewTxRunner(conn, &sql.TxOptions{}, nil)

	// Execute code inside a transaction
	err = runner.DoInTx(context.Background(), func(runner dbr.SessionRunner) error {
		// Perform database operations using the runner
		_, err := runner.InsertInto("users").
			Columns("name", "email").
			Values("Bob", "bob@example.com").
			Exec()
		if err != nil {
			return err
		}

		// Return nil to commit the transaction
		return nil
	})
	if err != nil {
		fmt.Println("Failed to execute transaction:", err)
		return
	}
}
Usage of distrlock package
// Create a new DBManager with the MySQL dialect
dbManager, err := distrlock.NewDBManager(db.DialectMySQL)
if err != nil {
    log.Fatal(err)
}

// Open a connection to the MySQL database
dbConn, err := sql.Open("mysql", "user:password@tcp(localhost:3306)/database")
if err != nil {
    log.Fatal(err)
}
defer dbConn.Close()

// Create a new lock
lock, err := dbManager.NewLock(context.Background(), dbConn, "my_lock")
if err != nil {
    log.Fatal(err)
}

// Acquire the lock
err = lock.Acquire(context.Background(), dbConn, 5*time.Second)
if err != nil {
    log.Fatal(err)
}

// Do some work while holding the lock
fmt.Println("Lock acquired, doing some work...")

// Release the lock
err = lock.Release(context.Background(), dbConn)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Lock released")

License

Copyright © 2024 Acronis International GmbH.

Licensed under MIT License.

Documentation

Overview

Package dbkit provides helpers for working with different SQL databases (MySQL, PostgreSQL, SQLite, and MSSQL).

Index

Constants

View Source 
const (
	DefaultMaxIdleConns    = 2
	DefaultMaxOpenConns    = 10
	DefaultConnMaxLifetime = 10 * time.Minute // Official recommendation from the DBA team
)

Default values of connection parameters

View Source 
const MSSQLDefaultTxLevel = sql.LevelReadCommitted

MSSQLDefaultTxLevel contains transaction isolation level which will be used by default for MSSQL.

View Source 
const (
	MetricsLabelQuery = "query"
)

Prometheus labels.

View Source 
const MySQLDefaultTxLevel = sql.LevelReadCommitted

MySQLDefaultTxLevel contains transaction isolation level which will be used by default for MySQL.

View Source 
const PgReadWriteParam = "read-write"

PgReadWriteParam read-write session attribute value name

View Source 
const PgTargetSessionAttrs = "target_session_attrs"

PgTargetSessionAttrs session attrs parameter name

View Source 
const PostgresDefaultSSLMode = PostgresSSLModeVerifyCA

PostgresDefaultSSLMode contains Postgres SSL mode which will be used by default.

View Source 
const PostgresDefaultTxLevel = sql.LevelReadCommitted

PostgresDefaultTxLevel contains transaction isolation level which will be used by default for Postgres.

Variables

View Source 
var DefaultQueryDurationBuckets = []float64{0.001, 0.01, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}

DefaultQueryDurationBuckets is default buckets into which observations of executing SQL queries are counted.

Functions

func DoInTx 

func DoInTx(ctx context.Context, dbConn *sql.DB, fn func(tx *sql.Tx) error) (err error)

DoInTx begins a new transaction, calls passed function and do commit or rollback depending on whether the function returns an error or not.

func DoInTxWithOpts 

func DoInTxWithOpts(ctx context.Context, dbConn *sql.DB, txOpts *sql.TxOptions, fn func(tx *sql.Tx) error) (err error)

DoInTxWithOpts is a bit more configurable version of DoInTx that allows passing tx options.

func GetIsRetryable 

func GetIsRetryable(d driver.Driver) retry.IsRetryable

GetIsRetryable returns a function that can tell for given driver if error is retryable.

func InitOpenedDB 

func InitOpenedDB(db *sql.DB, cfg *Config, ping bool) error

InitOpenedDB initializes early opened *sql.DB instance.

func MakeMSSQLDSN 

func MakeMSSQLDSN(cfg *MSSQLConfig) string

MakeMSSQLDSN makes DSN for opening MSSQL database.

func MakeMySQLDSN 

func MakeMySQLDSN(cfg *MySQLConfig) string

MakeMySQLDSN makes DSN for opening MySQL database.

func MakePostgresDSN 

func MakePostgresDSN(cfg *PostgresConfig) string

MakePostgresDSN makes DSN for opening Postgres database.

func MakeSQLiteDSN 

func MakeSQLiteDSN(cfg *SQLiteConfig) string

MakeSQLiteDSN makes DSN for opening SQLite database.

func RegisterIsRetryableFunc 

func RegisterIsRetryableFunc(d driver.Driver, retryable retry.IsRetryable)

RegisterIsRetryableFunc registers callback to determinate specific DB error is retryable or not. Several registered functions will be called one after another in FIFO order before some function returns true. Note: this function is not concurrent-safe. Typical scenario: register all custom IsRetryable in module init()

Types

type Config 

type Config struct {
	Dialect         Dialect
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime time.Duration
	MySQL           MySQLConfig
	MSSQL           MSSQLConfig
	SQLite          SQLiteConfig
	Postgres        PostgresConfig
	// contains filtered or unexported fields
}

Config represents a set of configuration parameters working with SQL databases.

func NewConfig 

func NewConfig(supportedDialects []Dialect) *Config

NewConfig creates a new instance of the Config.

func NewConfigWithKeyPrefix 

func NewConfigWithKeyPrefix(keyPrefix string, supportedDialects []Dialect) *Config

NewConfigWithKeyPrefix creates a new instance of the Config. Allows to specify key prefix which will be used for parsing configuration parameters.

func (*Config) DriverNameAndDSN 

func (c *Config) DriverNameAndDSN() (driverName, dsn string)

DriverNameAndDSN returns driver name and DSN for connecting.

func (*Config) KeyPrefix 

func (c *Config) KeyPrefix() string

KeyPrefix returns a key prefix with which all configuration parameters should be presented.

func (*Config) Set 

func (c *Config) Set(dp config.DataProvider) error

Set sets configuration values from config.DataProvider.

func (*Config) SetProviderDefaults 

func (c *Config) SetProviderDefaults(dp config.DataProvider)

SetProviderDefaults sets default configuration values in config.DataProvider.

func (*Config) SupportedDialects 

func (c *Config) SupportedDialects() []Dialect

SupportedDialects returns list of supported dialects.

func (*Config) TxIsolationLevel 

func (c *Config) TxIsolationLevel() sql.IsolationLevel

TxIsolationLevel returns transaction isolation level from parsed config for specified dialect.

type Dialect 

type Dialect string

Dialect defines possible values for planned supported SQL dialects. 

const (
	DialectSQLite   Dialect = "sqlite3"
	DialectMySQL    Dialect = "mysql"
	DialectPostgres Dialect = "postgres"
	DialectPgx      Dialect = "pgx"
	DialectMSSQL    Dialect = "mssql"
)

SQL dialects.

type MSSQLConfig 

type MSSQLConfig struct {
	Host             string
	Port             int
	User             string
	Password         string
	Database         string
	TxIsolationLevel sql.IsolationLevel
}

MSSQLConfig represents a set of configuration parameters for working with MSSQL.

type MetricsCollector 

type MetricsCollector struct {
	QueryDurations *prometheus.HistogramVec
}

MetricsCollector represents collector of metrics.

func NewMetricsCollector 

func NewMetricsCollector() *MetricsCollector

NewMetricsCollector creates a new metrics collector.

func NewMetricsCollectorWithOpts 

func NewMetricsCollectorWithOpts(opts MetricsCollectorOpts) *MetricsCollector

NewMetricsCollectorWithOpts is a more configurable version of creating MetricsCollector.

func (*MetricsCollector) AllMetrics 

func (c *MetricsCollector) AllMetrics() []prometheus.Collector

AllMetrics returns a list of metrics of this collector. This can be used to register these metrics in push gateway.

func (*MetricsCollector) MustCurryWith 

func (c *MetricsCollector) MustCurryWith(labels prometheus.Labels) *MetricsCollector

MustCurryWith curries the metrics collector with the provided labels.

func (*MetricsCollector) MustRegister 

func (c *MetricsCollector) MustRegister()

MustRegister does registration of metrics collector in Prometheus and panics if any error occurs.

func (*MetricsCollector) Unregister 

func (c *MetricsCollector) Unregister()

Unregister cancels registration of metrics collector in Prometheus.

type MetricsCollectorOpts 

type MetricsCollectorOpts struct {
	// Namespace is a namespace for metrics. It will be prepended to all metric names.
	Namespace string

	// QueryDurationBuckets is a list of buckets into which observations of executing SQL queries are counted.
	QueryDurationBuckets []float64

	// ConstLabels is a set of labels that will be applied to all metrics.
	ConstLabels prometheus.Labels

	// CurryingLabelNames is a list of label names that will be curried with the provided labels.
	// See MetricsCollector.MustCurryWith method for more details.
	// Keep in mind that if this list is not empty,
	// MetricsCollector.MustCurryWith method must be called further with the same labels.
	// Otherwise, the collector will panic.
	CurriedLabelNames []string
}

MetricsCollectorOpts represents an options for MetricsCollector.

type MySQLConfig 

type MySQLConfig struct {
	Host             string
	Port             int
	User             string
	Password         string
	Database         string
	TxIsolationLevel sql.IsolationLevel
}

MySQLConfig represents a set of configuration parameters for working with MySQL.

type Parameter 

type Parameter struct {
	Name  string
	Value string
}

Parameter represent DB connection parameter. Value will be url-encoded before adding into the connection string.

type PostgresConfig 

type PostgresConfig struct {
	Host                 string
	Port                 int
	User                 string
	Password             string
	Database             string
	TxIsolationLevel     sql.IsolationLevel
	SSLMode              PostgresSSLMode
	SearchPath           string
	AdditionalParameters []Parameter
}

PostgresConfig represents a set of configuration parameters for working with Postgres.

type PostgresErrCode 

type PostgresErrCode string

PostgresErrCode defines the type for Postgres error codes. 

const (
	PgxErrCodeUniqueViolation      PostgresErrCode = "23505"
	PgxErrCodeDeadlockDetected     PostgresErrCode = "40P01"
	PgxErrCodeSerializationFailure PostgresErrCode = "40001"
	PgxErrFeatureNotSupported      PostgresErrCode = "0A000"

	// nolint: staticcheck // lib/pq using is deprecated. Use pgx Postgres driver.
	PostgresErrCodeUniqueViolation PostgresErrCode = "unique_violation"
	// nolint: staticcheck // lib/pq using is deprecated. Use pgx Postgres driver.
	PostgresErrCodeDeadlockDetected     PostgresErrCode = "deadlock_detected"
	PostgresErrCodeSerializationFailure PostgresErrCode = "serialization_failure"
)

Postgres error codes (will be filled gradually).

type PostgresSSLMode 

type PostgresSSLMode string

PostgresSSLMode defines possible values for Postgres sslmode connection parameter. 

const (
	PostgresSSLModeDisable    PostgresSSLMode = "disable"
	PostgresSSLModeRequire    PostgresSSLMode = "require"
	PostgresSSLModeVerifyCA   PostgresSSLMode = "verify-ca"
	PostgresSSLModeVerifyFull PostgresSSLMode = "verify-full"
)

Postgres SSL modes.

type SQLiteConfig 

type SQLiteConfig struct {
	Path string
}

SQLiteConfig represents a set of configuration parameters for working with SQLite.

Source Files

View all Source files

Directories

Path Synopsis
Package dbrutil provides utilities and helpers for dbr query builder.
 Package dbrutil provides utilities and helpers for dbr query builder.
dbrtest
Package dbrtest provides objects and helpers for writings tests for code that uses dbr and dbrutils packages.
 Package dbrtest provides objects and helpers for writings tests for code that uses dbr and dbrutils packages.
Package distrlock contains DML (distributed lock manager) implementation (now DMLs based on MySQL and PostgreSQL are supported).
 Package distrlock contains DML (distributed lock manager) implementation (now DMLs based on MySQL and PostgreSQL are supported).
Package goquutil provides auxiliary routines for working with goqu query builder.
 Package goquutil provides auxiliary routines for working with goqu query builder.
internal
testing
Package testing contains internal testing utilities we apply in go-dbkit.
 Package testing contains internal testing utilities we apply in go-dbkit.
Package migrate provides functionality for applying database migrations.
 Package migrate provides functionality for applying database migrations.
Package mssql provides helpers for working MSSQL database.
 Package mssql provides helpers for working MSSQL database.
Package mysql provides helpers for working MySQL database.
 Package mysql provides helpers for working MySQL database.
Package pgx provides helpers for working Postgres database via jackc/pgx driver.
 Package pgx provides helpers for working Postgres database via jackc/pgx driver.
Package postgres provides helpers for working Postgres database.
 Package postgres provides helpers for working Postgres database.
Package sqlite provides helpers for working SQLite database.
 Package sqlite provides helpers for working SQLite database.

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.