pg

Documentation

Overview

Package pg provides small utilities for the lib/pq database driver.

It also registers the sql.Driver "hapg", which can resolve uris from the high-availability postgres package.

Index

• Variables
• func Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
• func ForQueryRows(ctx context.Context, db DB, query string, args ...interface{}) error
• func IsUniqueViolation(err error) bool
• func NewContext(ctx context.Context, db DB) context.Context
• func NewListener(ctx context.Context, dbURL, channel string) (*pq.Listener, error)
• func Query(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
• func QueryRow(ctx context.Context, query string, args ...interface{}) *sql.Row
• type Beginner
• type Committer
  • func Begin(ctx context.Context) (Committer, context.Context, error)
• type DB
  • func FromContext(ctx context.Context) DB
• type Tx
• type Uint32s
  • func (a *Uint32s) Scan(val interface{}) error
  • func (a Uint32s) Value() (driver.Value, error)

Variables

var ErrBadRequest = errors.New("bad request")

var ErrUserInputNotFound = errors.New("pg: user input not found")

ErrUserInputNotFound indicates that a query returned no results. It is equivalent to sql.ErrNoRows, except that ErrUserInputNotFound also indicates the query was based on user-provided parameters, and the lack of results should be communicated back to the user.

In contrast, we use sql.ErrNoRows to represent an internal error; this indicates a bug in our code and only a generic "internal error" message should be communicated back to the user.

Functions

func Exec

func Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

Exec is a short form of FromContext(ctx).Exec

func ForQueryRows

func ForQueryRows(ctx context.Context, db DB, query string, args ...interface{}) error

ForQueryRows encapsulates a lot of boilerplate when making db queries. Call it like this:

err = ForQueryRows(ctx, db, query, queryArg1, queryArg2, ..., func(scanVar1 type1, scanVar2 type2, ...) {
  ...process a row from the result...
})

This is equivalent to:

rows, err = db.Query(ctx, query, queryArg1, queryArg2, ...)
if err != nil {
  return err
}
defer rows.Close()
for rows.Next() {
  var (
    scanVar1 type1
    scanVar2 type2
  )
  err = rows.Scan(&scanVar1, &scanVar2, ...)
  if err != nil {
    return err
  }
  ...process a row from the result...
}
if err = rows.Err(); err != nil {
  return err
}

The callback is invoked once for each row in the result. The number and types of parameters to the callback must match the values to be scanned with rows.Scan. The space for the callback's arguments is not reused between calls. The callback may return a single error-type value. If any invocation yields a non-nil result, ForQueryRows will abort and return it.

func IsUniqueViolation

func IsUniqueViolation(err error) bool

IsUniqueViolation returns true if the given error is a Postgres unique constraint violation error.

func NewContext

func NewContext(ctx context.Context, db DB) context.Context

NewContext returns a new Context that carries value db.

func NewListener

func NewListener(ctx context.Context, dbURL, channel string) (*pq.Listener, error)

NewListener creates a new pq.Listener and begins listening.

func Query

func Query(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

Query is a short form of FromContext(ctx).Query

func QueryRow

func QueryRow(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRow is a short form of FromContext(ctx).QueryRow

Types

type Beginner

type Beginner interface {
	Begin(context.Context) (Tx, error)
}

Beginner is used by Begin to create a new transaction. It is an optional alternative to the Begin signature provided by package sql.

type Committer

type Committer interface {
	Commit(context.Context) error
	Rollback(context.Context) error
}

Committer provides methods to commit or roll back a single transaction.

func Begin

func Begin(ctx context.Context) (Committer, context.Context, error)

Begin opens a new transaction on the database stored in ctx. The stored database must provide a Begin method like sql.DB or satisfy the interface Beginner. Begin returns the new transaction and a new context with the transaction as its associated database.

Note: if a transaction is already pending in the passed-in context, this function does not create a new one but returns the existing one.

type DB

type DB interface {
	Query(context.Context, string, ...interface{}) (*sql.Rows, error)
	QueryRow(context.Context, string, ...interface{}) *sql.Row
	Exec(context.Context, string, ...interface{}) (sql.Result, error)
}

DB holds methods common to the DB, Tx, and Stmt types in package sql.

func FromContext

func FromContext(ctx context.Context) DB

FromContext returns the DB value stored in ctx. If there is no DB value, FromContext panics.

type Tx

type Tx interface {
	DB
	Committer
}

Tx represents a SQL transaction. Type sql.Tx satisfies this interface.

type Uint32s

type Uint32s []uint32

func (*Uint32s) Scan

func (a *Uint32s) Scan(val interface{}) error

func (Uint32s) Value

func (a Uint32s) Value() (driver.Value, error)