sqlutil

Documentation

Index

• func EndTransaction(txn *sql.Tx, succeeded *bool) error
• func TxStmt(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 Writer
  • func NewDummyWriter() Writer
  • func NewExclusiveWriter() Writer

Functions

func EndTransaction

func EndTransaction(txn *sql.Tx, 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 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 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 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