sqlutil

Documentation

Index

• Constants
• Variables
• func EndTransaction(txn Transaction, succeeded *bool) error
• func EndTransactionWithCheck(txn Transaction, succeeded *bool, err *error)
• func InsertMigration(ctx context.Context, db *sql.DB, migrationName string) error
• func IsUniqueConstraintViolationErr(err error) bool
• func Open(dbProperties *config.DatabaseOptions, writer Writer) (*sql.DB, error)
• func ParseFileURI(dataSourceName config.DataSource) (string, error)
• func QueryVariadic(count int) string
• func QueryVariadicOffset(count, offset int) string
• func RunLimitedVariablesExec(ctx context.Context, query string, qp ExecProvider, variables []interface{}, ...) error
• func RunLimitedVariablesQuery(ctx context.Context, query string, qp QueryProvider, variables []interface{}, ...) error
• func TxStmt(transaction *sql.Tx, statement *sql.Stmt) *sql.Stmt
• func TxStmtContext(context context.Context, transaction *sql.Tx, statement *sql.Stmt) *sql.Stmt
• func WithTransaction(db *sql.DB, fn func(txn *sql.Tx) error) (err error)
• type Connections
  • func NewConnectionManager(processCtx *process.ProcessContext, globalConfig config.DatabaseOptions) *Connections
  • func (c *Connections) Connection(dbProperties *config.DatabaseOptions) (*sql.DB, Writer, error)
• type DummyWriter
  • func (w *DummyWriter) Do(db *sql.DB, txn *sql.Tx, f func(txn *sql.Tx) error) error
• type ExclusiveWriter
  • func (w *ExclusiveWriter) Do(db *sql.DB, txn *sql.Tx, f func(txn *sql.Tx) error) error
• type ExecProvider
• type Migration
• type Migrator
  • func NewMigrator(db *sql.DB) *Migrator
  • func (m *Migrator) AddMigrations(migrations ...Migration)
  • func (m *Migrator) ExecutedMigrations(ctx context.Context) (map[string]struct{}, error)
  • func (m *Migrator) Up(ctx context.Context) error
• type QueryProvider
• type StatementList
  • func (s StatementList) Prepare(db *sql.DB) (err error)
• type Transaction
• type Writer
  • func NewDummyWriter() Writer
  • func NewExclusiveWriter() Writer

Constants

const SQLITE_DRIVER_NAME = "sqlite3"

const SQLite3MaxVariables = 999

SQLite3MaxVariables is the default maximum number of host parameters in a single SQL statement SQLlite can handle. See https://www.sqlite.org/limits.html for more information.

Variables

var ErrUserExists = errors.New("username already exists")

ErrUserExists is returned if a username already exists in the database.

Functions

func EndTransaction

func EndTransaction(txn Transaction, succeeded *bool) error

EndTransaction ends a transaction. If the transaction succeeded then it is committed, otherwise it is rolledback. You MUST check the error returned from this function to be sure that the transaction was applied correctly. For example, 'database is locked' errors in sqlite will happen here.

func EndTransactionWithCheck

func EndTransactionWithCheck(txn Transaction, succeeded *bool, err *error)

EndTransactionWithCheck ends a transaction and overwrites the error pointer if its value was nil. If the transaction succeeded then it is committed, otherwise it is rolledback. Designed to be used with defer (see EndTransaction otherwise).

func InsertMigration

func InsertMigration(ctx context.Context, db *sql.DB, migrationName string) error

InsertMigration creates the migrations table if it doesn't exist and inserts a migration given their name to the database. This should only be used when manually inserting migrations.

func IsUniqueConstraintViolationErr

func IsUniqueConstraintViolationErr(err error) bool

IsUniqueConstraintViolationErr returns true if the error is an unique_violation error

func Open

func Open(dbProperties *config.DatabaseOptions, writer Writer) (*sql.DB, error)

Open opens a database specified by its database driver name and a driver-specific data source name, usually consisting of at least a database name and connection information.

func ParseFileURI

func ParseFileURI(dataSourceName config.DataSource) (string, error)

ParseFileURI returns the filepath in the given file: URI. Specifically, this will handle both relative (file:foo.db) and absolute (file:///path/to/foo) paths.

func QueryVariadic

func QueryVariadic(count int) string

Hack of the century

func QueryVariadicOffset

func QueryVariadicOffset(count, offset int) string

func RunLimitedVariablesExec

func RunLimitedVariablesExec(ctx context.Context, query string, qp ExecProvider, variables []interface{}, limit uint) error

RunLimitedVariablesExec split up a query with more variables than the used database can handle in multiple queries.

func RunLimitedVariablesQuery

func RunLimitedVariablesQuery(ctx context.Context, query string, qp QueryProvider, variables []interface{}, limit uint, rowHandler func(*sql.Rows) error) error

RunLimitedVariablesQuery split up a query with more variables than the used database can handle in multiple queries.

func TxStmt

func TxStmt(transaction *sql.Tx, statement *sql.Stmt) *sql.Stmt

TxStmt wraps an SQL stmt inside an optional transaction. If the transaction is nil then it returns the original statement that will run outside of a transaction. Otherwise returns a copy of the statement that will run inside the transaction.

func TxStmtContext

func TxStmtContext(context context.Context, transaction *sql.Tx, statement *sql.Stmt) *sql.Stmt

TxStmtContext behaves similarly to TxStmt, with support for also passing context.

func WithTransaction

func WithTransaction(db *sql.DB, fn func(txn *sql.Tx) error) (err error)

WithTransaction runs a block of code passing in an SQL transaction If the code returns an error or panics then the transactions is rolledback Otherwise the transaction is committed.

Types

type Connections

type Connections struct {
	// contains filtered or unexported fields
}

func NewConnectionManager

func NewConnectionManager(processCtx *process.ProcessContext, globalConfig config.DatabaseOptions) *Connections

func (*Connections) Connection

func (c *Connections) Connection(dbProperties *config.DatabaseOptions) (*sql.DB, Writer, error)

type DummyWriter

type DummyWriter struct {
}

DummyWriter implements sqlutil.Writer. The DummyWriter is designed to allow reuse of the sqlutil.Writer interface but, unlike ExclusiveWriter, it will not guarantee writer exclusivity. This is fine in PostgreSQL where overlapping transactions and writes are acceptable.

func (*DummyWriter) Do

func (w *DummyWriter) Do(db *sql.DB, txn *sql.Tx, f func(txn *sql.Tx) error) error

type ExclusiveWriter

type ExclusiveWriter struct {
	// contains filtered or unexported fields
}

ExclusiveWriter implements sqlutil.Writer. ExclusiveWriter allows queuing database writes so that you don't contend on database locks in, e.g. SQLite. Only one task will run at a time on a given ExclusiveWriter.

func (*ExclusiveWriter) Do

func (w *ExclusiveWriter) Do(db *sql.DB, txn *sql.Tx, f func(txn *sql.Tx) error) error

Do queues a task to be run by a TransactionWriter. The function provided will be ran within a transaction as supplied by the txn parameter if one is supplied, and if not, will take out a new transaction from the database supplied in the database parameter. Either way, this will block until the task is done.

type ExecProvider

type ExecProvider interface {
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
}

ExecProvider defines the interface for querys used by RunLimitedVariablesExec.

type Migration

type Migration struct {
	// Version is a simple description/name of this migration.
	Version string
	// Up defines the function to execute for an upgrade.
	Up func(ctx context.Context, txn *sql.Tx) error
	// Down defines the function to execute for a downgrade (not implemented yet).
	Down func(ctx context.Context, txn *sql.Tx) error
}

Migration defines a migration to be run.

type Migrator

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator contains fields required to run migrations.

func NewMigrator

func NewMigrator(db *sql.DB) *Migrator

NewMigrator creates a new DB migrator.

func (*Migrator) AddMigrations

func (m *Migrator) AddMigrations(migrations ...Migration)

AddMigrations appends migrations to the list of migrations. Migrations are executed in the order they are added to the list. De-duplicates migrations using their Version field.

func (*Migrator) ExecutedMigrations

func (m *Migrator) ExecutedMigrations(ctx context.Context) (map[string]struct{}, error)

ExecutedMigrations returns a map with already executed migrations in addition to creating the migrations table, if it doesn't exist.

func (*Migrator) Up

func (m *Migrator) Up(ctx context.Context) error

Up executes all migrations in order they were added.

type QueryProvider

type QueryProvider interface {
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
}

QueryProvider defines the interface for querys used by RunLimitedVariablesQuery.

type StatementList

type StatementList []struct {
	Statement **sql.Stmt
	SQL       string
}

StatementList is a list of SQL statements to prepare and a pointer to where to store the resulting prepared statement.

func (StatementList) Prepare

func (s StatementList) Prepare(db *sql.DB) (err error)

Prepare the SQL for each statement in the list and assign the result to the prepared statement.

type Transaction

type Transaction interface {
	// Commit the transaction
	Commit() error
	// Rollback the transaction.
	Rollback() error
}

A Transaction is something that can be committed or rolledback.

type Writer

type Writer interface {
	// Queue up one or more database write operations within the
	// provided function to be executed when it is safe to do so.
	Do(db *sql.DB, txn *sql.Tx, f func(txn *sql.Tx) error) error
}

The Writer interface is designed to solve the problem of how to handle database writes for database engines that don't allow concurrent writes, e.g. SQLite.

The interface has a single Do function which takes an optional database parameter, an optional transaction parameter and a required function parameter. The Writer will call the function provided when it is safe to do so, optionally providing a transaction to use.

Depending on the combination of parameters provided, the Writer will behave in one of three ways:

1. `db` provided, `txn` provided:

The Writer will call f() when it is safe to do so. The supplied "txn" will ALWAYS be passed through to f(). Use this when you already have a transaction open.

2. `db` provided, `txn` not provided (nil):

The Writer will open a new transaction on the provided database and then will call f() when it is safe to do so. The new transaction will ALWAYS be passed through to f(). Use this if you plan to perform more than one SQL query within f().

3. `db` not provided (nil), `txn` not provided (nil):

The Writer will call f() when it is safe to do so, but will not make any attempt to open a new database transaction or to pass through an existing one. The "txn" parameter within f() will ALWAYS be nil in this mode. This is useful if you just want to perform a single query on an already-prepared statement without the overhead of opening a new transaction to do it in.

You MUST take particular care not to call Do() from within f() on the same Writer, or it will likely result in a deadlock.

func NewDummyWriter

func NewDummyWriter() Writer

NewDummyWriter returns a new dummy writer.

func NewExclusiveWriter

func NewExclusiveWriter() Writer