sqlutil

Documentation

Index

• Constants
• Variables
• func EndTransaction(txn Transaction, succeeded *bool) error
• func EndTransactionWithCheck(txn Transaction, succeeded *bool, err *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 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 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 Migrations
  • func NewMigrations() *Migrations
  • func (m *Migrations) AddMigration(up func(*sql.Tx) error, down func(*sql.Tx) error)
  • func (m *Migrations) AddNamedMigration(filename string, up func(*sql.Tx) error, down func(*sql.Tx) error)
  • func (m *Migrations) RunDeltas(db *sql.DB, props *config.DatabaseOptions) 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 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 IsUniqueConstraintViolationErr

func IsUniqueConstraintViolationErr(err error) bool

IsUniqueConstraintViolationErr returns true if the error is a postgresql 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. Includes tracing driver if DENDRITE_TRACE_SQL=1

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 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 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 Migrations

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

func NewMigrations

func NewMigrations() *Migrations

func (*Migrations) AddMigration

func (m *Migrations) AddMigration(up func(*sql.Tx) error, down func(*sql.Tx) error)

AddMigration adds a migration.

func (*Migrations) AddNamedMigration

func (m *Migrations) AddNamedMigration(filename string, up func(*sql.Tx) error, down func(*sql.Tx) error)

AddNamedMigration : Add a named migration.

func (*Migrations) RunDeltas

func (m *Migrations) RunDeltas(db *sql.DB, props *config.DatabaseOptions) error

RunDeltas up to the latest version.

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