db

Documentation

Overview

Package db includes database functionality for Pixur.

Index

• Constants
• func AllocId(ctx context.Context, beg Beginner, alloc *IdAlloc, adap DBAdapter) (int64, error)
• func AllocIdJob(ctx context.Context, qe querierExecutor, alloc *IdAlloc, adap DBAdapter) (int64, error)
• func Delete(exec Executor, name string, key UniqueIdx, adap DBAdapter) error
• func Insert(exec Executor, name string, cols []string, vals []interface{}, adap DBAdapter) error
• func PreallocateIds(ctx context.Context, beg Beginner, alloc *IdAlloc, adap DBAdapter) error
• func RegisterAdapter(a DBAdapter)
• func Scan(q Querier, name string, opts Opts, cb func(data []byte) error, adap DBAdapter) error
• func Update(exec Executor, name string, cols []string, vals []interface{}, key UniqueIdx, ...) error
• type Beginner
• type Columns
• type Commiter
• type DB
  • func Open(ctx context.Context, adapterName, dataSourceName string) (DB, error)
  • func OpenForTest(ctx context.Context, adapterName string) (DB, error)
• type DBAdaptable
• type DBAdapter
  • func GetAllAdapters() []DBAdapter
• type Executor
• type IdAlloc
  • func (alloc *IdAlloc) GetWatermark() (lo, hi int64)
  • func (alloc *IdAlloc) SetWatermark(newlo, newhi int64)
• type IdAllocatable
• type Idx
• type Lock
• type Opts
• type Querier
• type QuerierExecutorCommitter
• type Result
• type Retryable
• type Rows
• type UniqueIdx

Constants

const (
	SequenceTableName = "_SequenceTable"
	SequenceColName   = "the_sequence"
)

const (
	DefaultIdLowWaterMark  = 1
	DefaultIdHighWaterMark = 10
)

Watermarks determines how many Ids will be grabbed at a time. If the number is too high program restarts will waste Id space. Additionally, Ids will become less monotonic if there are multiple servers. If the number is too low, it will make a lot more queries than necessary.

Functions

func AllocId

func AllocId(ctx context.Context, beg Beginner, alloc *IdAlloc, adap DBAdapter) (int64, error)

Don't use this unless outside of an existing Job.

func AllocIdJob

func AllocIdJob(ctx context.Context, qe querierExecutor, alloc *IdAlloc, adap DBAdapter) (
	int64, error)

func Delete

func Delete(exec Executor, name string, key UniqueIdx, adap DBAdapter) error

func Insert

func Insert(exec Executor, name string, cols []string, vals []interface{}, adap DBAdapter) error

func PreallocateIds

func PreallocateIds(ctx context.Context, beg Beginner, alloc *IdAlloc, adap DBAdapter) error

PreallocateIds attempts to fill the cache in IdAlloc. It is best effort. If the number of cached Ids goes below the low watermark, PreallocateIds will attempt to get more. It will attempt to refill up to the high watermark.

func RegisterAdapter

func RegisterAdapter(a DBAdapter)

func Scan

func Scan(q Querier, name string, opts Opts, cb func(data []byte) error, adap DBAdapter) error

Scan scans a table for matching rows.

func Update

func Update(exec Executor, name string, cols []string, vals []interface{}, key UniqueIdx,
	adap DBAdapter) error

Types

type Beginner

type Beginner interface {
	// Begin begins a transaction
	Begin(ctx context.Context, readonly bool) (QuerierExecutorCommitter, error)
}

Beginner begins transactions. Upon a successful call to Begin(), callers should take care to either Commit() or Rollback() the QuerierExecutorCommitter.

type Columns

type Columns []string

type Commiter

type Commiter interface {
	// Commit returns nil iff the transaction was successful.  This method may only be called once.
	// If this method returns true, future calls to Rollback() will be no-ops and always return nil.
	// If an error is returned, the transaction may have been successful, or it may have failed.
	Commit() error
	// Rollback reverts the transaction.  Invocations after first are no-ops and always return nil.
	// If an error is returned, the caller does not need to call Rollback() again.
	Rollback() error
}

Commiter is an interface to commit transactions. It is not threadsafe

type DB

type DB interface {
	DBAdaptable
	IdAllocatable
	Beginner
	// Close closes the database, and should be called when the db is no longer needed.
	Close() error
	// InitSchema initializes the database tables.  This is typically used in unit tests.
	InitSchema(context.Context, []string) error
}

DB represents a database. It is the entry point to creating transactions.

func Open

func Open(ctx context.Context, adapterName, dataSourceName string) (DB, error)

Open is the main entry point to the db package. adapterName is one of the registered types. dataSourceName is the connection information to initiate the db.

func OpenForTest

func OpenForTest(ctx context.Context, adapterName string) (DB, error)

type DBAdaptable

type DBAdaptable interface {
	// Adapter returns an adapter for use with a database.
	Adapter() DBAdapter
}

type DBAdapter

type DBAdapter interface {
	Name() string
	Quote(string) string
	BlobIdxQuote(string) string
	LockStmt(*strings.Builder, Lock)
	BoolType() string
	IntType() string
	BigIntType() string
	BlobType() string

	Open(ctx context.Context, dataSourceName string) (DB, error)
	OpenForTest(context.Context) (DB, error)

	// Can the given error be retried?
	RetryableErr(error) bool
}

func GetAllAdapters

func GetAllAdapters() []DBAdapter

type Executor

type Executor interface {
	Exec(string, ...interface{}) (Result, error)
}

type IdAlloc

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

IdAlloc is an id allocator

func (*IdAlloc) GetWatermark

func (alloc *IdAlloc) GetWatermark() (lo, hi int64)

GetWatermark returns the low and high watermark. See SetWatermark.

func (*IdAlloc) SetWatermark

func (alloc *IdAlloc) SetWatermark(newlo, newhi int64)

SetWatermark sets the low and high watermark for Id allocation. See PreallocateIds.

type IdAllocatable

type IdAllocatable interface {
	// IdAllocator returns an IdAlloc for use with a database.
	IdAllocator() *IdAlloc
}

type Idx

type Idx interface {
	Cols() []string
	Vals() []interface{}
}

type Lock

type Lock int

const (
	LockNone  Lock = -1
	LockRead  Lock = 0
	LockWrite Lock = 1
)

type Opts

type Opts struct {
	Prefix Idx
	// At most one of StartInc and StartEx may be set
	StartInc, StartEx Idx
	// At most one of StopInc and StopEx may be set
	StopInc, StopEx Idx
	Lock            Lock
	Reverse         bool
	Limit           int
}

type Querier

type Querier interface {
	Query(query string, args ...interface{}) (Rows, error)
}

type QuerierExecutorCommitter

type QuerierExecutorCommitter interface {
	Querier
	Commiter
	Executor
}

QuerierExecutorCommitter is an interface that matches the sql.Tx type.

type Result

type Result interface {
	LastInsertId() (int64, error)
	RowsAffected() (int64, error)
}

Result is a clone of database/sql.Result

type Retryable

type Retryable interface {
	CanRetry() bool
}

Retryable is implemented by errors that can describe their retryability.

type Rows

type Rows interface {
	Close() error
	Columns() ([]string, error)
	Err() error
	Next() bool
	Scan(dest ...interface{}) error
}

Rows is a clone of database/sql.Rows

type UniqueIdx

type UniqueIdx interface {
	Idx
	Unique()
}

UniqueIdx is a tagging interface that indentifies indexes that uniquely identify a row. Columns that are UNIQUE or PRIMARY fit this interface.