pgx - ActiveState ActiveGo 1.8
...

Package pgx

import "github.com/jackc/pgx"
Overview
Index
Subdirectories

Overview ▾

Package pgx is a PostgreSQL database driver.

pgx provides lower level access to PostgreSQL than the standard database/sql It remains as similar to the database/sql interface as possible while providing better speed and access to PostgreSQL specific features. Import github.com/jack/pgx/stdlib to use pgx as a database/sql compatible driver.

Query Interface

pgx implements Query and Scan in the familiar database/sql style.

var sum int32

// Send the query to the server. The returned rows MUST be closed
// before conn can be used again.
rows, err := conn.Query("select generate_series(1,$1)", 10)
if err != nil {
    return err
}

// rows.Close is called by rows.Next when all rows are read
// or an error occurs in Next or Scan. So it may optionally be
// omitted if nothing in the rows.Next loop can panic. It is
// safe to close rows multiple times.
defer rows.Close()

// Iterate through the result set
for rows.Next() {
    var n int32
    err = rows.Scan(&n)
    if err != nil {
        return err
    }
    sum += n
}

// Any errors encountered by rows.Next or rows.Scan will be returned here
if rows.Err() != nil {
    return err
}

// No errors found - do something with sum

pgx also implements QueryRow in the same style as database/sql.

var name string
var weight int64
err := conn.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
    return err
}

Use Exec to execute a query that does not return a result set.

commandTag, err := conn.Exec("delete from widgets where id=$1", 42)
if err != nil {
    return err
}
if commandTag.RowsAffected() != 1 {
    return errors.New("No row found to delete")
}

Connection Pool

Connection pool usage is explicit and configurable. In pgx, a connection can be created and managed directly, or a connection pool with a configurable maximum connections can be used. Also, the connection pool offers an after connect hook that allows every connection to be automatically setup before being made available in the connection pool. This is especially useful to ensure all connections have the same prepared statements available or to change any other connection settings.

It delegates Query, QueryRow, Exec, and Begin functions to an automatically checked out and released connection so you can avoid manually acquiring and releasing connections when you do not need that level of control.

var name string
var weight int64
err := pool.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
    return err
}

Base Type Mapping

pgx maps between all common base types directly between Go and PostgreSQL. In particular:

Go           PostgreSQL
-----------------------
string       varchar
             text

// Integers are automatically be converted to any other integer type if
// it can be done without overflow or underflow.
int8
int16        smallint
int32        int
int64        bigint
int
uint8
uint16
uint32
uint64
uint

// Floats are strict and do not automatically convert like integers.
float32      float4
float64      float8

time.Time   date
            timestamp
            timestamptz

[]byte      bytea

Null Mapping

pgx can map nulls in two ways. The first is Null* types that have a data field and a valid field. They work in a similar fashion to database/sql. The second is to use a pointer to a pointer.

var foo pgx.NullString
var bar *string
err := conn.QueryRow("select foo, bar from widgets where id=$1", 42).Scan(&a, &b)
if err != nil {
    return err
}

Array Mapping

pgx maps between int16, int32, int64, float32, float64, and string Go slices and the equivalent PostgreSQL array type. Go slices of native types do not support nulls, so if a PostgreSQL array that contains a null is read into a native Go slice an error will occur.

Hstore Mapping

pgx includes an Hstore type and a NullHstore type. Hstore is simply a map[string]string and is preferred when the hstore contains no nulls. NullHstore follows the Null* pattern and supports null values.

JSON and JSONB Mapping

pgx includes built-in support to marshal and unmarshal between Go types and the PostgreSQL JSON and JSONB.

Inet and Cidr Mapping

pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In addition, as a convenience pgx will encode from a net.IP; it will assume a /32 netmask for IPv4 and a /128 for IPv6.

Custom Type Support

pgx includes support for the common data types like integers, floats, strings, dates, and times that have direct mappings between Go and SQL. Support can be added for additional types like point, hstore, numeric, etc. that do not have direct mappings in Go by the types implementing ScannerPgx and Encoder.

Custom types can support text or binary formats. Binary format can provide a large performance increase. The natural place for deciding the format for a value would be in ScannerPgx as it is responsible for decoding the returned data. However, that is impossible as the query has already been sent by the time the ScannerPgx is invoked. The solution to this is the global DefaultTypeFormats. If a custom type prefers binary format it should register it there.

pgx.DefaultTypeFormats["point"] = pgx.BinaryFormatCode

Note that the type is referred to by name, not by OID. This is because custom PostgreSQL types like hstore will have different OIDs on different servers. When pgx establishes a connection it queries the pg_type table for all types. It then matches the names in DefaultTypeFormats with the returned OIDs and stores it in Conn.PgTypes.

See example_custom_type_test.go for an example of a custom type for the PostgreSQL point type.

pgx also includes support for custom types implementing the database/sql.Scanner and database/sql/driver.Valuer interfaces.

Raw Bytes Mapping

[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified to PostgreSQL. In like manner, a *[]byte passed to Scan will be filled with the raw bytes returned by PostgreSQL. This can be especially useful for reading varchar, text, json, and jsonb values directly into a []byte and avoiding the type conversion from string.

Transactions

Transactions are started by calling Begin or BeginIso. The BeginIso variant creates a transaction with a specified isolation level.

tx, err := conn.Begin()
if err != nil {
    return err
}
// Rollback is safe to call even if the tx is already closed, so if
// the tx commits successfully, this is a no-op
defer tx.Rollback()

_, err = tx.Exec("insert into foo(id) values (1)")
if err != nil {
    return err
}

err = tx.Commit()
if err != nil {
    return err
}

Copy Protocol

Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL copy protocol. CopyFrom accepts a CopyFromSource interface. If the data is already in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource interface. Or implement CopyFromSource to avoid buffering the entire data set in memory.

rows := [][]interface{}{
    {"John", "Smith", int32(36)},
    {"Jane", "Doe", int32(29)},
}

copyCount, err := conn.CopyFrom(
    "people",
    []string{"first_name", "last_name", "age"},
    pgx.CopyFromRows(rows),
)

CopyFrom can be faster than an insert with as few as 5 rows.

Listen and Notify

pgx can listen to the PostgreSQL notification system with the WaitForNotification function. It takes a maximum time to wait for a notification.

err := conn.Listen("channelname")
if err != nil {
    return nil
}

if notification, err := conn.WaitForNotification(time.Second); err != nil {
    // do something with notification
}

TLS

The pgx ConnConfig struct has a TLSConfig field. If this field is nil, then TLS will be disabled. If it is present, then it will be used to configure the TLS connection. This allows total configuration of the TLS connection.

Logging

pgx defines a simple logger interface. Connections optionally accept a logger that satisfies this interface. The log15 package (http://gopkg.in/inconshreveable/log15.v2) satisfies this interface and it is simple to define adapters for other loggers. Set LogLevel to control logging verbosity.

Index ▾

Constants
Variables
func Decode(vr *ValueReader, d interface{}) error
func Encode(wbuf *WriteBuf, oid Oid, arg interface{}) error
func FormatLSN(lsn uint64) string
func LogLevelFromString(s string) (int, error)
func ParseHstore(s string) (k []string, v []NullString, err error)
func ParseLSN(lsn string) (outputLsn uint64, err error)
type AclItem
type Char
type Cid
type CommandTag
    func (ct CommandTag) RowsAffected() int64
type Conn
    func Connect(config ConnConfig) (c *Conn, err error)
    func (c *Conn) Begin() (*Tx, error)
    func (c *Conn) BeginIso(isoLevel string) (*Tx, error)
    func (c *Conn) CauseOfDeath() error
    func (c *Conn) Close() (err error)
    func (c *Conn) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)
    func (c *Conn) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)
    func (c *Conn) Deallocate(name string) (err error)
    func (c *Conn) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)
    func (c *Conn) IsAlive() bool
    func (c *Conn) Listen(channel string) error
    func (c *Conn) Prepare(name, sql string) (ps *PreparedStatement, err error)
    func (c *Conn) PrepareEx(name, sql string, opts *PrepareExOptions) (ps *PreparedStatement, err error)
    func (c *Conn) Query(sql string, args ...interface{}) (*Rows, error)
    func (c *Conn) QueryRow(sql string, args ...interface{}) *Row
    func (c *Conn) SetLogLevel(lvl int) (int, error)
    func (c *Conn) SetLogger(logger Logger) Logger
    func (c *Conn) Unlisten(channel string) error
    func (c *Conn) WaitForNotification(timeout time.Duration) (*Notification, error)
type ConnConfig
    func ParseConnectionString(s string) (ConnConfig, error)
    func ParseDSN(s string) (ConnConfig, error)
    func ParseEnvLibpq() (ConnConfig, error)
    func ParseURI(uri string) (ConnConfig, error)
type ConnPool
    func NewConnPool(config ConnPoolConfig) (p *ConnPool, err error)
    func (p *ConnPool) Acquire() (*Conn, error)
    func (p *ConnPool) Begin() (*Tx, error)
    func (p *ConnPool) BeginIso(iso string) (*Tx, error)
    func (p *ConnPool) Close()
    func (p *ConnPool) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)
    func (p *ConnPool) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)
    func (p *ConnPool) Deallocate(name string) (err error)
    func (p *ConnPool) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)
    func (p *ConnPool) Prepare(name, sql string) (*PreparedStatement, error)
    func (p *ConnPool) PrepareEx(name, sql string, opts *PrepareExOptions) (*PreparedStatement, error)
    func (p *ConnPool) Query(sql string, args ...interface{}) (*Rows, error)
    func (p *ConnPool) QueryRow(sql string, args ...interface{}) *Row
    func (p *ConnPool) Release(conn *Conn)
    func (p *ConnPool) Reset()
    func (p *ConnPool) Stat() (s ConnPoolStat)
type ConnPoolConfig
type ConnPoolStat
type CopyFromSource
    func CopyFromRows(rows [][]interface{}) CopyFromSource
type CopyToSource
    func CopyToRows(rows [][]interface{}) CopyToSource
type DialFunc
type Encoder
type FieldDescription
type Hstore
    func (h Hstore) Encode(w *WriteBuf, oid Oid) error
    func (h Hstore) FormatCode() int16
    func (h *Hstore) Scan(vr *ValueReader) error
type Identifier
    func (ident Identifier) Sanitize() string
type LargeObject
    func (o *LargeObject) Close() error
    func (o *LargeObject) Read(p []byte) (int, error)
    func (o *LargeObject) Seek(offset int64, whence int) (n int64, err error)
    func (o *LargeObject) Tell() (n int64, err error)
    func (o *LargeObject) Truncate(size int64) (err error)
    func (o *LargeObject) Write(p []byte) (int, error)
type LargeObjectMode
type LargeObjects
    func (o *LargeObjects) Create(id Oid) (Oid, error)
    func (o *LargeObjects) Open(oid Oid, mode LargeObjectMode) (*LargeObject, error)
    func (o *LargeObjects) Unlink(oid Oid) error
type Logger
type Name
type Notification
type NullAclItem
    func (n NullAclItem) Encode(w *WriteBuf, oid Oid) error
    func (n NullAclItem) FormatCode() int16
    func (n *NullAclItem) Scan(vr *ValueReader) error
type NullBool
    func (n NullBool) Encode(w *WriteBuf, oid Oid) error
    func (n NullBool) FormatCode() int16
    func (n *NullBool) Scan(vr *ValueReader) error
type NullChar
    func (n NullChar) Encode(w *WriteBuf, oid Oid) error
    func (n NullChar) FormatCode() int16
    func (n *NullChar) Scan(vr *ValueReader) error
type NullCid
    func (n NullCid) Encode(w *WriteBuf, oid Oid) error
    func (n NullCid) FormatCode() int16
    func (n *NullCid) Scan(vr *ValueReader) error
type NullFloat32
    func (n NullFloat32) Encode(w *WriteBuf, oid Oid) error
    func (n NullFloat32) FormatCode() int16
    func (n *NullFloat32) Scan(vr *ValueReader) error
type NullFloat64
    func (n NullFloat64) Encode(w *WriteBuf, oid Oid) error
    func (n NullFloat64) FormatCode() int16
    func (n *NullFloat64) Scan(vr *ValueReader) error
type NullHstore
    func (h NullHstore) Encode(w *WriteBuf, oid Oid) error
    func (h NullHstore) FormatCode() int16
    func (h *NullHstore) Scan(vr *ValueReader) error
type NullInt16
    func (n NullInt16) Encode(w *WriteBuf, oid Oid) error
    func (n NullInt16) FormatCode() int16
    func (n *NullInt16) Scan(vr *ValueReader) error
type NullInt32
    func (n NullInt32) Encode(w *WriteBuf, oid Oid) error
    func (n NullInt32) FormatCode() int16
    func (n *NullInt32) Scan(vr *ValueReader) error
type NullInt64
    func (n NullInt64) Encode(w *WriteBuf, oid Oid) error
    func (n NullInt64) FormatCode() int16
    func (n *NullInt64) Scan(vr *ValueReader) error
type NullName
    func (n NullName) Encode(w *WriteBuf, oid Oid) error
    func (n NullName) FormatCode() int16
    func (n *NullName) Scan(vr *ValueReader) error
type NullOid
    func (n NullOid) Encode(w *WriteBuf, oid Oid) error
    func (n NullOid) FormatCode() int16
    func (n *NullOid) Scan(vr *ValueReader) error
type NullString
    func (n NullString) Encode(w *WriteBuf, oid Oid) error
    func (n NullString) FormatCode() int16
    func (n *NullString) Scan(vr *ValueReader) error
type NullTid
    func (n NullTid) Encode(w *WriteBuf, oid Oid) error
    func (n NullTid) FormatCode() int16
    func (n *NullTid) Scan(vr *ValueReader) error
type NullTime
    func (n NullTime) Encode(w *WriteBuf, oid Oid) error
    func (n NullTime) FormatCode() int16
    func (n *NullTime) Scan(vr *ValueReader) error
type NullXid
    func (n NullXid) Encode(w *WriteBuf, oid Oid) error
    func (n NullXid) FormatCode() int16
    func (n *NullXid) Scan(vr *ValueReader) error
type Oid
type PgError
    func (pe PgError) Error() string
type PgType
type PgxScanner
type PrepareExOptions
type PreparedStatement
type ProtocolError
    func (e ProtocolError) Error() string
type QueryArgs
    func (qa *QueryArgs) Append(v interface{}) string
type ReplicationConn
    func ReplicationConnect(config ConnConfig) (r *ReplicationConn, err error)
    func (rc *ReplicationConn) CauseOfDeath() error
    func (rc *ReplicationConn) Close() error
    func (rc *ReplicationConn) CreateReplicationSlot(slotName, outputPlugin string) (err error)
    func (rc *ReplicationConn) DropReplicationSlot(slotName string) (err error)
    func (rc *ReplicationConn) IdentifySystem() (r *Rows, err error)
    func (rc *ReplicationConn) IsAlive() bool
    func (rc *ReplicationConn) SendStandbyStatus(k *StandbyStatus) (err error)
    func (rc *ReplicationConn) StartReplication(slotName string, startLsn uint64, timeline int64, pluginArguments ...string) (err error)
    func (rc *ReplicationConn) TimelineHistory(timeline int) (r *Rows, err error)
    func (rc *ReplicationConn) WaitForReplicationMessage(timeout time.Duration) (r *ReplicationMessage, err error)
type ReplicationMessage
type Row
    func (r *Row) Scan(dest ...interface{}) (err error)
type Rows
    func (rows *Rows) AfterClose(f func(*Rows))
    func (rows *Rows) Close()
    func (rows *Rows) Conn() *Conn
    func (rows *Rows) Err() error
    func (rows *Rows) Fatal(err error)
    func (rows *Rows) FieldDescriptions() []FieldDescription
    func (rows *Rows) Next() bool
    func (rows *Rows) Scan(dest ...interface{}) (err error)
    func (rows *Rows) Values() ([]interface{}, error)
type Scanner
type SerializationError
    func (e SerializationError) Error() string
type ServerHeartbeat
    func (s *ServerHeartbeat) String() string
    func (s *ServerHeartbeat) Time() time.Time
type StandbyStatus
    func NewStandbyStatus(walPositions ...uint64) (status *StandbyStatus, err error)
type Tid
type Tx
    func (tx *Tx) AfterClose(f func(*Tx))
    func (tx *Tx) Commit() error
    func (tx *Tx) Conn() *Conn
    func (tx *Tx) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)
    func (tx *Tx) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)
    func (tx *Tx) Err() error
    func (tx *Tx) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)
    func (tx *Tx) LargeObjects() (*LargeObjects, error)
    func (tx *Tx) Prepare(name, sql string) (*PreparedStatement, error)
    func (tx *Tx) PrepareEx(name, sql string, opts *PrepareExOptions) (*PreparedStatement, error)
    func (tx *Tx) Query(sql string, args ...interface{}) (*Rows, error)
    func (tx *Tx) QueryRow(sql string, args ...interface{}) *Row
    func (tx *Tx) Rollback() error
    func (tx *Tx) Status() int8
type ValueReader
    func (r *ValueReader) Err() error
    func (r *ValueReader) Fatal(err error)
    func (r *ValueReader) Len() int32
    func (r *ValueReader) ReadByte() byte
    func (r *ValueReader) ReadBytes(count int32) []byte
    func (r *ValueReader) ReadInt16() int16
    func (r *ValueReader) ReadInt32() int32
    func (r *ValueReader) ReadInt64() int64
    func (r *ValueReader) ReadOid() Oid
    func (r *ValueReader) ReadString(count int32) string
    func (r *ValueReader) ReadUint16() uint16
    func (r *ValueReader) ReadUint32() uint32
    func (r *ValueReader) Type() *FieldDescription
type WalMessage
    func (w *WalMessage) ByteLag() uint64
    func (w *WalMessage) String() string
    func (w *WalMessage) Time() time.Time
type WriteBuf
    func (wb *WriteBuf) WriteByte(b byte)
    func (wb *WriteBuf) WriteBytes(b []byte)
    func (wb *WriteBuf) WriteCString(s string)
    func (wb *WriteBuf) WriteInt16(n int16)
    func (wb *WriteBuf) WriteInt32(n int32)
    func (wb *WriteBuf) WriteInt64(n int64)
    func (wb *WriteBuf) WriteUint16(n uint16)
    func (wb *WriteBuf) WriteUint32(n uint32)
type Xid

Package files

conn.go conn_pool.go copy_from.go copy_to.go doc.go fastpath.go hstore.go large_objects.go logger.go messages.go msg_reader.go pgpass.go query.go replication.go sql.go tx.go value_reader.go values.go

Constants

The values for log levels are chosen such that the zero value means that no log level was specified and we can default to LogLevelDebug to preserve the behavior that existed prior to log level introduction.

const (
    LogLevelTrace = 6
    LogLevelDebug = 5
    LogLevelInfo  = 4
    LogLevelWarn  = 3
    LogLevelError = 2
    LogLevelNone  = 1
)

Transaction isolation levels

const (
    Serializable    = "serializable"
    RepeatableRead  = "repeatable read"
    ReadCommitted   = "read committed"
    ReadUncommitted = "read uncommitted"
)
const (
    TxStatusInProgress      = 0
    TxStatusCommitFailure   = -1
    TxStatusRollbackFailure = -2
    TxStatusCommitSuccess   = 1
    TxStatusRollbackSuccess = 2
)

PostgreSQL oids for common types

const (
    BoolOid             = 16
    ByteaOid            = 17
    CharOid             = 18
    NameOid             = 19
    Int8Oid             = 20
    Int2Oid             = 21
    Int4Oid             = 23
    TextOid             = 25
    OidOid              = 26
    TidOid              = 27
    XidOid              = 28
    CidOid              = 29
    JsonOid             = 114
    CidrOid             = 650
    CidrArrayOid        = 651
    Float4Oid           = 700
    Float8Oid           = 701
    UnknownOid          = 705
    InetOid             = 869
    BoolArrayOid        = 1000
    Int2ArrayOid        = 1005
    Int4ArrayOid        = 1007
    TextArrayOid        = 1009
    ByteaArrayOid       = 1001
    VarcharArrayOid     = 1015
    Int8ArrayOid        = 1016
    Float4ArrayOid      = 1021
    Float8ArrayOid      = 1022
    AclItemOid          = 1033
    AclItemArrayOid     = 1034
    InetArrayOid        = 1041
    VarcharOid          = 1043
    DateOid             = 1082
    TimestampOid        = 1114
    TimestampArrayOid   = 1115
    TimestampTzOid      = 1184
    TimestampTzArrayOid = 1185
    RecordOid           = 2249
    UuidOid             = 2950
    JsonbOid            = 3802
)

PostgreSQL format codes

const (
    TextFormatCode   = 0
    BinaryFormatCode = 1
)

Variables

DefaultTypeFormats maps type names to their default requested format (text or binary). In theory the Scanner interface should be the one to determine the format of the returned values. However, the query has already been executed by the time Scan is called so it has no chance to set the format. So for types that should always be returned in binary the format should be set here.

var DefaultTypeFormats map[string]int16

ErrAcquireTimeout occurs when an attempt to acquire a connection times out.

var ErrAcquireTimeout = errors.New("timeout acquiring connection from pool")

ErrConnBusy occurs when the connection is busy (for example, in the middle of reading query results) and another action is attempts.

var ErrConnBusy = errors.New("conn is busy")

ErrDeadConn occurs on an attempt to use a dead connection

var ErrDeadConn = errors.New("conn is dead")

ErrInvalidLogLevel occurs on attempt to set an invalid log level.

var ErrInvalidLogLevel = errors.New("invalid log level")

ErrNoRows occurs when rows are expected but none are returned.

var ErrNoRows = errors.New("no rows in result set")

ErrNotificationTimeout occurs when WaitForNotification times out.

var ErrNotificationTimeout = errors.New("notification timeout")

ErrTLSRefused occurs when the connection attempt requires TLS and the PostgreSQL server refuses to use TLS

var ErrTLSRefused = errors.New("server refused TLS connection")
var ErrTxClosed = errors.New("tx is closed")

ErrTxCommitRollback occurs when an error has occurred in a transaction and Commit() is called. PostgreSQL accepts COMMIT on aborted transactions, but it is treated as ROLLBACK.

var ErrTxCommitRollback = errors.New("commit unexpectedly resulted in rollback")

func Decode

func Decode(vr *ValueReader, d interface{}) error

Decode decodes from vr into d. d must be a pointer. This allows implementations of the Decoder interface to delegate the actual work of decoding to the built-in functionality.

func Encode

func Encode(wbuf *WriteBuf, oid Oid, arg interface{}) error

Encode encodes arg into wbuf as the type oid. This allows implementations of the Encoder interface to delegate the actual work of encoding to the built-in functionality.

func FormatLSN

func FormatLSN(lsn uint64) string

Format the given 64bit LSN value into the XXX/XXX format, which is the format reported by postgres.

func LogLevelFromString

func LogLevelFromString(s string) (int, error)

LogLevelFromString converts log level string to constant

Valid levels:

trace
debug
info
warn
error
none

func ParseHstore

func ParseHstore(s string) (k []string, v []NullString, err error)

ParseHstore parses the string representation of an hstore column (the same you would get from an ordinary SELECT) into two slices of keys and values. it is used internally in the default parsing of hstores, but is exported for use in handling custom data structures backed by an hstore column without the overhead of creating a map[string]string

func ParseLSN

func ParseLSN(lsn string) (outputLsn uint64, err error)

Parse the given XXX/XXX format LSN as reported by postgres, into a 64 bit integer as used internally by the wire procotols

type AclItem

AclItem is used for PostgreSQL's aclitem data type. A sample aclitem might look like this:

postgres=arwdDxt/postgres

Note, however, that because the user/role name part of an aclitem is an identifier, it follows all the usual formatting rules for SQL identifiers: if it contains spaces and other special characters, it should appear in double-quotes:

postgres=arwdDxt/"role with spaces"
type AclItem string

type Char

The pgx.Char type is for PostgreSQL's special 8-bit-only "char" type more akin to the C language's char type, or Go's byte type. (Note that the name in PostgreSQL itself is "char", in double-quotes, and not char.) It gets used a lot in PostgreSQL's system tables to hold a single ASCII character value (eg pg_class.relkind).

type Char byte

type Cid

Cid is PostgreSQL's Command Identifier type.

When one does

select cmin, cmax, * from some_table;

it is the data type of the cmin and cmax hidden system columns.

It is currently implemented as an unsigned four byte integer. Its definition can be found in src/include/c.h as CommandId in the PostgreSQL sources.

type Cid uint32

type CommandTag

CommandTag is the result of an Exec function

type CommandTag string

func (CommandTag) RowsAffected

func (ct CommandTag) RowsAffected() int64

RowsAffected returns the number of rows affected. If the CommandTag was not for a row affecting command (such as "CREATE TABLE") then it returns 0

type Conn

Conn is a PostgreSQL connection handle. It is not safe for concurrent usage. Use ConnPool to manage access to multiple database connections from multiple goroutines.

type Conn struct {
    Pid           int32             // backend pid
    SecretKey     int32             // key to use to send a cancel query message to the server
    RuntimeParams map[string]string // parameters that have been reported by the server
    PgTypes       map[Oid]PgType    // oids to PgTypes

    TxStatus byte
    // contains filtered or unexported fields
}

func Connect

func Connect(config ConnConfig) (c *Conn, err error)

Connect establishes a connection with a PostgreSQL server using config. config.Host must be specified. config.User will default to the OS user name. Other config fields are optional.

func (*Conn) Begin

func (c *Conn) Begin() (*Tx, error)

Begin starts a transaction with the default isolation level for the current connection. To use a specific isolation level see BeginIso.

func (*Conn) BeginIso

func (c *Conn) BeginIso(isoLevel string) (*Tx, error)

BeginIso starts a transaction with isoLevel as the transaction isolation level.

Valid isolation levels (and their constants) are:

serializable (pgx.Serializable)
repeatable read (pgx.RepeatableRead)
read committed (pgx.ReadCommitted)
read uncommitted (pgx.ReadUncommitted)

func (*Conn) CauseOfDeath

func (c *Conn) CauseOfDeath() error

func (*Conn) Close

func (c *Conn) Close() (err error)

Close closes a connection. It is safe to call Close on a already closed connection.

func (*Conn) CopyFrom

func (c *Conn) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)

CopyFrom uses the PostgreSQL copy protocol to perform bulk data insertion. It returns the number of rows copied and an error.

CopyFrom requires all values use the binary format. Almost all types implemented by pgx use the binary format by default. Types implementing Encoder can only be used if they encode to the binary format.

func (*Conn) CopyTo

func (c *Conn) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)

Deprecated. Use CopyFrom instead. CopyTo uses the PostgreSQL copy protocol to perform bulk data insertion. It returns the number of rows copied and an error.

CopyTo requires all values use the binary format. Almost all types implemented by pgx use the binary format by default. Types implementing Encoder can only be used if they encode to the binary format.

func (*Conn) Deallocate

func (c *Conn) Deallocate(name string) (err error)

Deallocate released a prepared statement

func (*Conn) Exec

func (c *Conn) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)

Exec executes sql. sql can be either a prepared statement name or an SQL string. arguments should be referenced positionally from the sql string as $1, $2, etc.

func (*Conn) IsAlive

func (c *Conn) IsAlive() bool

func (*Conn) Listen

func (c *Conn) Listen(channel string) error

Listen establishes a PostgreSQL listen/notify to channel

func (*Conn) Prepare

func (c *Conn) Prepare(name, sql string) (ps *PreparedStatement, err error)

Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These placeholders are referenced positional as $1, $2, etc.

Prepare is idempotent; i.e. it is safe to call Prepare multiple times with the same name and sql arguments. This allows a code path to Prepare and Query/Exec without concern for if the statement has already been prepared.

func (*Conn) PrepareEx

func (c *Conn) PrepareEx(name, sql string, opts *PrepareExOptions) (ps *PreparedStatement, err error)

PrepareEx creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These placeholders are referenced positional as $1, $2, etc. It defers from Prepare as it allows additional options (such as parameter OIDs) to be passed via struct

PrepareEx is idempotent; i.e. it is safe to call PrepareEx multiple times with the same name and sql arguments. This allows a code path to PrepareEx and Query/Exec without concern for if the statement has already been prepared.

func (*Conn) Query

func (c *Conn) Query(sql string, args ...interface{}) (*Rows, error)

Query executes sql with args. If there is an error the returned *Rows will be returned in an error state. So it is allowed to ignore the error returned from Query and handle it in *Rows.

func (*Conn) QueryRow

func (c *Conn) QueryRow(sql string, args ...interface{}) *Row

QueryRow is a convenience wrapper over Query. Any error that occurs while querying is deferred until calling Scan on the returned *Row. That *Row will error with ErrNoRows if no rows are returned.

func (*Conn) SetLogLevel

func (c *Conn) SetLogLevel(lvl int) (int, error)

SetLogLevel replaces the current log level and returns the previous log level.

func (*Conn) SetLogger

func (c *Conn) SetLogger(logger Logger) Logger

SetLogger replaces the current logger and returns the previous logger.

func (*Conn) Unlisten

func (c *Conn) Unlisten(channel string) error

Unlisten unsubscribes from a listen channel

func (*Conn) WaitForNotification

func (c *Conn) WaitForNotification(timeout time.Duration) (*Notification, error)

WaitForNotification waits for a PostgreSQL notification for up to timeout. If the timeout occurs it returns pgx.ErrNotificationTimeout

type ConnConfig

ConnConfig contains all the options used to establish a connection.

type ConnConfig struct {
    Host              string // host (e.g. localhost) or path to unix domain socket directory (e.g. /private/tmp)
    Port              uint16 // default: 5432
    Database          string
    User              string // default: OS user name
    Password          string
    TLSConfig         *tls.Config // config for TLS connection -- nil disables TLS
    UseFallbackTLS    bool        // Try FallbackTLSConfig if connecting with TLSConfig fails. Used for preferring TLS, but allowing unencrypted, or vice-versa
    FallbackTLSConfig *tls.Config // config for fallback TLS connection (only used if UseFallBackTLS is true)-- nil disables TLS
    Logger            Logger
    LogLevel          int
    Dial              DialFunc
    RuntimeParams     map[string]string // Run-time parameters to set on connection as session default values (e.g. search_path or application_name)
}

func ParseConnectionString

func ParseConnectionString(s string) (ConnConfig, error)

ParseConnectionString parses either a URI or a DSN connection string. see ParseURI and ParseDSN for details.

func ParseDSN

func ParseDSN(s string) (ConnConfig, error)

ParseDSN parses a database DSN (data source name) into a ConnConfig

e.g. ParseDSN("user=username password=password host=1.2.3.4 port=5432 dbname=mydb sslmode=disable")

Any options not used by the connection process are parsed into ConnConfig.RuntimeParams.

e.g. ParseDSN("application_name=pgxtest search_path=admin user=username password=password host=1.2.3.4 dbname=mydb")

ParseDSN tries to match libpq behavior with regard to sslmode. See comments for ParseEnvLibpq for more information on the security implications of sslmode options.

func ParseEnvLibpq

func ParseEnvLibpq() (ConnConfig, error)

ParseEnvLibpq parses the environment like libpq does into a ConnConfig

See http://www.postgresql.org/docs/9.4/static/libpq-envars.html for details on the meaning of environment variables.

ParseEnvLibpq currently recognizes the following environment variables: PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGSSLMODE PGAPPNAME

Important TLS Security Notes: ParseEnvLibpq tries to match libpq behavior with regard to PGSSLMODE. This includes defaulting to "prefer" behavior if no environment variable is set.

See http://www.postgresql.org/docs/9.4/static/libpq-ssl.html#LIBPQ-SSL-PROTECTION for details on what level of security each sslmode provides.

"require" and "verify-ca" modes currently are treated as "verify-full". e.g. They have stronger security guarantees than they would with libpq. Do not rely on this behavior as it may be possible to match libpq in the future. If you need full security use "verify-full".

Several of the PGSSLMODE options (including the default behavior of "prefer") will set UseFallbackTLS to true and FallbackTLSConfig to a disabled or weakened TLS mode. This means that if ParseEnvLibpq is used, but TLSConfig is later set from a different source that UseFallbackTLS MUST be set false to avoid the possibility of falling back to weaker or disabled security.

func ParseURI

func ParseURI(uri string) (ConnConfig, error)

ParseURI parses a database URI into ConnConfig

Query parameters not used by the connection process are parsed into ConnConfig.RuntimeParams.

type ConnPool

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

func NewConnPool

func NewConnPool(config ConnPoolConfig) (p *ConnPool, err error)

NewConnPool creates a new ConnPool. config.ConnConfig is passed through to Connect directly.

func (*ConnPool) Acquire

func (p *ConnPool) Acquire() (*Conn, error)

Acquire takes exclusive use of a connection until it is released.

func (*ConnPool) Begin

func (p *ConnPool) Begin() (*Tx, error)

Begin acquires a connection and begins a transaction on it. When the transaction is closed the connection will be automatically released.

func (*ConnPool) BeginIso

func (p *ConnPool) BeginIso(iso string) (*Tx, error)

BeginIso acquires a connection and begins a transaction in isolation mode iso on it. When the transaction is closed the connection will be automatically released.

func (*ConnPool) Close

func (p *ConnPool) Close()

Close ends the use of a connection pool. It prevents any new connections from being acquired, waits until all acquired connections are released, then closes all underlying connections.

func (*ConnPool) CopyFrom

func (p *ConnPool) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)

CopyFrom acquires a connection, delegates the call to that connection, and releases the connection.

func (*ConnPool) CopyTo

func (p *ConnPool) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)

Deprecated. Use CopyFrom instead. CopyTo acquires a connection, delegates the call to that connection, and releases the connection.

func (*ConnPool) Deallocate

func (p *ConnPool) Deallocate(name string) (err error)

Deallocate releases a prepared statement from all connections in the pool.

func (*ConnPool) Exec

func (p *ConnPool) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)

Exec acquires a connection, delegates the call to that connection, and releases the connection

func (*ConnPool) Prepare

func (p *ConnPool) Prepare(name, sql string) (*PreparedStatement, error)

Prepare creates a prepared statement on a connection in the pool to test the statement is valid. If it succeeds all connections accessed through the pool will have the statement available.

Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These placeholders are referenced positional as $1, $2, etc.

Prepare is idempotent; i.e. it is safe to call Prepare multiple times with the same name and sql arguments. This allows a code path to Prepare and Query/Exec/PrepareEx without concern for if the statement has already been prepared.

func (*ConnPool) PrepareEx

func (p *ConnPool) PrepareEx(name, sql string, opts *PrepareExOptions) (*PreparedStatement, error)

PrepareEx creates a prepared statement on a connection in the pool to test the statement is valid. If it succeeds all connections accessed through the pool will have the statement available.

PrepareEx creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These placeholders are referenced positional as $1, $2, etc. It defers from Prepare as it allows additional options (such as parameter OIDs) to be passed via struct

PrepareEx is idempotent; i.e. it is safe to call PrepareEx multiple times with the same name and sql arguments. This allows a code path to PrepareEx and Query/Exec/Prepare without concern for if the statement has already been prepared.

func (*ConnPool) Query

func (p *ConnPool) Query(sql string, args ...interface{}) (*Rows, error)

Query acquires a connection and delegates the call to that connection. When *Rows are closed, the connection is released automatically.

func (*ConnPool) QueryRow

func (p *ConnPool) QueryRow(sql string, args ...interface{}) *Row

QueryRow acquires a connection and delegates the call to that connection. The connection is released automatically after Scan is called on the returned *Row.

func (*ConnPool) Release

func (p *ConnPool) Release(conn *Conn)

Release gives up use of a connection.

func (*ConnPool) Reset

func (p *ConnPool) Reset()

Reset closes all open connections, but leaves the pool open. It is intended for use when an error is detected that would disrupt all connections (such as a network interruption or a server state change).

It is safe to reset a pool while connections are checked out. Those connections will be closed when they are returned to the pool.

func (*ConnPool) Stat

func (p *ConnPool) Stat() (s ConnPoolStat)

Stat returns connection pool statistics

type ConnPoolConfig

type ConnPoolConfig struct {
    ConnConfig
    MaxConnections int               // max simultaneous connections to use, default 5, must be at least 2
    AfterConnect   func(*Conn) error // function to call on every new connection
    AcquireTimeout time.Duration     // max wait time when all connections are busy (0 means no timeout)
}

type ConnPoolStat

type ConnPoolStat struct {
    MaxConnections       int // max simultaneous connections to use
    CurrentConnections   int // current live connections
    AvailableConnections int // unused live connections
}

type CopyFromSource

CopyFromSource is the interface used by *Conn.CopyFrom as the source for copy data.

type CopyFromSource interface {
    // Next returns true if there is another row and makes the next row data
    // available to Values(). When there are no more rows available or an error
    // has occurred it returns false.
    Next() bool

    // Values returns the values for the current row.
    Values() ([]interface{}, error)

    // Err returns any error that has been encountered by the CopyFromSource. If
    // this is not nil *Conn.CopyFrom will abort the copy.
    Err() error
}

func CopyFromRows

func CopyFromRows(rows [][]interface{}) CopyFromSource

CopyFromRows returns a CopyFromSource interface over the provided rows slice making it usable by *Conn.CopyFrom.

type CopyToSource

Deprecated. Use CopyFromSource instead. CopyToSource is the interface used by *Conn.CopyTo as the source for copy data.

type CopyToSource interface {
    // Next returns true if there is another row and makes the next row data
    // available to Values(). When there are no more rows available or an error
    // has occurred it returns false.
    Next() bool

    // Values returns the values for the current row.
    Values() ([]interface{}, error)

    // Err returns any error that has been encountered by the CopyToSource. If
    // this is not nil *Conn.CopyTo will abort the copy.
    Err() error
}

func CopyToRows

func CopyToRows(rows [][]interface{}) CopyToSource

Deprecated. Use CopyFromRows instead. CopyToRows returns a CopyToSource interface over the provided rows slice making it usable by *Conn.CopyTo.

type DialFunc

DialFunc is a function that can be used to connect to a PostgreSQL server

type DialFunc func(network, addr string) (net.Conn, error)

type Encoder

Encoder is an interface used to encode values for transmission to the PostgreSQL server.

type Encoder interface {
    // Encode writes the value to w.
    //
    // If the value is NULL an int32(-1) should be written.
    //
    // Encode MUST check oid to see if the parameter data type is compatible. If
    // this is not done, the PostgreSQL server may detect the error if the
    // expected data size or format of the encoded data does not match. But if
    // the encoded data is a valid representation of the data type PostgreSQL
    // expects such as date and int4, incorrect data may be stored.
    Encode(w *WriteBuf, oid Oid) error

    // FormatCode returns the format that the encoder writes the value. It must be
    // either pgx.TextFormatCode or pgx.BinaryFormatCode.
    FormatCode() int16
}

type FieldDescription

type FieldDescription struct {
    Name            string
    Table           Oid
    AttributeNumber int16
    DataType        Oid
    DataTypeSize    int16
    DataTypeName    string
    Modifier        int32
    FormatCode      int16
}

type Hstore

Hstore represents an hstore column. It does not support a null column or null key values (use NullHstore for this). Hstore implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

type Hstore map[string]string

func (Hstore) Encode

func (h Hstore) Encode(w *WriteBuf, oid Oid) error

func (Hstore) FormatCode

func (h Hstore) FormatCode() int16

func (*Hstore) Scan

func (h *Hstore) Scan(vr *ValueReader) error

type Identifier

Identifier a PostgreSQL identifier or name. Identifiers can be composed of multiple parts such as ["schema", "table"] or ["table", "column"].

type Identifier []string

func (Identifier) Sanitize

func (ident Identifier) Sanitize() string

Sanitize returns a sanitized string safe for SQL interpolation.

type LargeObject

A LargeObject is a large object stored on the server. It is only valid within the transaction that it was initialized in. It implements these interfaces:

io.Writer
io.Reader
io.Seeker
io.Closer
type LargeObject struct {
    // contains filtered or unexported fields
}

func (*LargeObject) Close

func (o *LargeObject) Close() error

Close closees the large object descriptor.

func (*LargeObject) Read

func (o *LargeObject) Read(p []byte) (int, error)

Read reads up to len(p) bytes into p returning the number of bytes read.

func (*LargeObject) Seek

func (o *LargeObject) Seek(offset int64, whence int) (n int64, err error)

Seek moves the current location pointer to the new location specified by offset.

func (*LargeObject) Tell

func (o *LargeObject) Tell() (n int64, err error)

Tell returns the current read or write location of the large object descriptor.

func (*LargeObject) Truncate

func (o *LargeObject) Truncate(size int64) (err error)

Trunctes the large object to size.

func (*LargeObject) Write

func (o *LargeObject) Write(p []byte) (int, error)

Write writes p to the large object and returns the number of bytes written and an error if not all of p was written.

type LargeObjectMode

type LargeObjectMode int32
const (
    LargeObjectModeWrite LargeObjectMode = 0x20000
    LargeObjectModeRead  LargeObjectMode = 0x40000
)

type LargeObjects

LargeObjects is a structure used to access the large objects API. It is only valid within the transaction where it was created.

For more details see: http://www.postgresql.org/docs/current/static/largeobjects.html

type LargeObjects struct {
    // Has64 is true if the server is capable of working with 64-bit numbers
    Has64 bool
    // contains filtered or unexported fields
}

func (*LargeObjects) Create

func (o *LargeObjects) Create(id Oid) (Oid, error)

Create creates a new large object. If id is zero, the server assigns an unused OID.

func (*LargeObjects) Open

func (o *LargeObjects) Open(oid Oid, mode LargeObjectMode) (*LargeObject, error)

Open opens an existing large object with the given mode.

func (o *LargeObjects) Unlink(oid Oid) error

Unlink removes a large object from the database.

type Logger

Logger is the interface used to get logging from pgx internals. https://github.com/inconshreveable/log15 is the recommended logging package. This logging interface was extracted from there. However, it should be simple to adapt any logger to this interface.

type Logger interface {
    // Log a message at the given level with context key/value pairs
    Debug(msg string, ctx ...interface{})
    Info(msg string, ctx ...interface{})
    Warn(msg string, ctx ...interface{})
    Error(msg string, ctx ...interface{})
}

type Name

Name is a type used for PostgreSQL's special 63-byte name data type, used for identifiers like table names. The pg_class.relname column is a good example of where the name data type is used.

Note that the underlying Go data type of pgx.Name is string, so there is no way to enforce the 63-byte length. Inputting a longer name into PostgreSQL will result in silent truncation to 63 bytes.

Also, if you have custom-compiled PostgreSQL and set NAMEDATALEN to a different value, obviously that number of bytes applies, rather than the default 63.

type Name string

type Notification

Notification is a message received from the PostgreSQL LISTEN/NOTIFY system

type Notification struct {
    Pid     int32  // backend pid that sent the notification
    Channel string // channel from which notification was received
    Payload string
}

type NullAclItem

NullAclItem represents a pgx.AclItem that may be null. NullAclItem implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan for prepared and unprepared queries.

If Valid is false then the value is NULL.

type NullAclItem struct {
    AclItem AclItem
    Valid   bool // Valid is true if AclItem is not NULL
}

func (NullAclItem) Encode

func (n NullAclItem) Encode(w *WriteBuf, oid Oid) error

func (NullAclItem) FormatCode

func (n NullAclItem) FormatCode() int16

Particularly important to return TextFormatCode, seeing as Postgres only ever sends aclitem as text, not binary.

func (*NullAclItem) Scan

func (n *NullAclItem) Scan(vr *ValueReader) error

type NullBool

NullBool represents an bool that may be null. NullBool implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullBool struct {
    Bool  bool
    Valid bool // Valid is true if Bool is not NULL
}

func (NullBool) Encode

func (n NullBool) Encode(w *WriteBuf, oid Oid) error

func (NullBool) FormatCode

func (n NullBool) FormatCode() int16

func (*NullBool) Scan

func (n *NullBool) Scan(vr *ValueReader) error

type NullChar

NullChar represents a pgx.Char that may be null. NullChar implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan for prepared and unprepared queries.

If Valid is false then the value is NULL.

type NullChar struct {
    Char  Char
    Valid bool // Valid is true if Char is not NULL
}

func (NullChar) Encode

func (n NullChar) Encode(w *WriteBuf, oid Oid) error

func (NullChar) FormatCode

func (n NullChar) FormatCode() int16

func (*NullChar) Scan

func (n *NullChar) Scan(vr *ValueReader) error

type NullCid

NullCid represents a Command Identifier (Cid) that may be null. NullCid implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullCid struct {
    Cid   Cid
    Valid bool // Valid is true if Cid is not NULL
}

func (NullCid) Encode

func (n NullCid) Encode(w *WriteBuf, oid Oid) error

func (NullCid) FormatCode

func (n NullCid) FormatCode() int16

func (*NullCid) Scan

func (n *NullCid) Scan(vr *ValueReader) error

type NullFloat32

NullFloat32 represents an float4 that may be null. NullFloat32 implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullFloat32 struct {
    Float32 float32
    Valid   bool // Valid is true if Float32 is not NULL
}

func (NullFloat32) Encode

func (n NullFloat32) Encode(w *WriteBuf, oid Oid) error

func (NullFloat32) FormatCode

func (n NullFloat32) FormatCode() int16

func (*NullFloat32) Scan

func (n *NullFloat32) Scan(vr *ValueReader) error

type NullFloat64

NullFloat64 represents an float8 that may be null. NullFloat64 implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullFloat64 struct {
    Float64 float64
    Valid   bool // Valid is true if Float64 is not NULL
}

func (NullFloat64) Encode

func (n NullFloat64) Encode(w *WriteBuf, oid Oid) error

func (NullFloat64) FormatCode

func (n NullFloat64) FormatCode() int16

func (*NullFloat64) Scan

func (n *NullFloat64) Scan(vr *ValueReader) error

type NullHstore

NullHstore represents an hstore column that can be null or have null values associated with its keys. NullHstore implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false, then the value of the entire hstore column is NULL If any of the NullString values in Store has Valid set to false, the key appears in the hstore column, but its value is explicitly set to NULL.

type NullHstore struct {
    Hstore map[string]NullString
    Valid  bool
}

func (NullHstore) Encode

func (h NullHstore) Encode(w *WriteBuf, oid Oid) error

func (NullHstore) FormatCode

func (h NullHstore) FormatCode() int16

func (*NullHstore) Scan

func (h *NullHstore) Scan(vr *ValueReader) error

type NullInt16

NullInt16 represents a smallint that may be null. NullInt16 implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan for prepared and unprepared queries.

If Valid is false then the value is NULL.

type NullInt16 struct {
    Int16 int16
    Valid bool // Valid is true if Int16 is not NULL
}

func (NullInt16) Encode

func (n NullInt16) Encode(w *WriteBuf, oid Oid) error

func (NullInt16) FormatCode

func (n NullInt16) FormatCode() int16

func (*NullInt16) Scan

func (n *NullInt16) Scan(vr *ValueReader) error

type NullInt32

NullInt32 represents an integer that may be null. NullInt32 implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullInt32 struct {
    Int32 int32
    Valid bool // Valid is true if Int32 is not NULL
}

func (NullInt32) Encode

func (n NullInt32) Encode(w *WriteBuf, oid Oid) error

func (NullInt32) FormatCode

func (n NullInt32) FormatCode() int16

func (*NullInt32) Scan

func (n *NullInt32) Scan(vr *ValueReader) error

type NullInt64

NullInt64 represents an bigint that may be null. NullInt64 implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullInt64 struct {
    Int64 int64
    Valid bool // Valid is true if Int64 is not NULL
}

func (NullInt64) Encode

func (n NullInt64) Encode(w *WriteBuf, oid Oid) error

func (NullInt64) FormatCode

func (n NullInt64) FormatCode() int16

func (*NullInt64) Scan

func (n *NullInt64) Scan(vr *ValueReader) error

type NullName

NullName represents a pgx.Name that may be null. NullName implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan for prepared and unprepared queries.

If Valid is false then the value is NULL.

type NullName struct {
    Name  Name
    Valid bool // Valid is true if Name is not NULL
}

func (NullName) Encode

func (n NullName) Encode(w *WriteBuf, oid Oid) error

func (NullName) FormatCode

func (n NullName) FormatCode() int16

func (*NullName) Scan

func (n *NullName) Scan(vr *ValueReader) error

type NullOid

NullOid represents a Command Identifier (Oid) that may be null. NullOid implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullOid struct {
    Oid   Oid
    Valid bool // Valid is true if Oid is not NULL
}

func (NullOid) Encode

func (n NullOid) Encode(w *WriteBuf, oid Oid) error

func (NullOid) FormatCode

func (n NullOid) FormatCode() int16

func (*NullOid) Scan

func (n *NullOid) Scan(vr *ValueReader) error

type NullString

NullString represents an string that may be null. NullString implements the Scanner Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullString struct {
    String string
    Valid  bool // Valid is true if String is not NULL
}

func (NullString) Encode

func (n NullString) Encode(w *WriteBuf, oid Oid) error

func (NullString) FormatCode

func (n NullString) FormatCode() int16

func (*NullString) Scan

func (n *NullString) Scan(vr *ValueReader) error

type NullTid

NullTid represents a Tuple Identifier (Tid) that may be null. NullTid implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullTid struct {
    Tid   Tid
    Valid bool // Valid is true if Tid is not NULL
}

func (NullTid) Encode

func (n NullTid) Encode(w *WriteBuf, oid Oid) error

func (NullTid) FormatCode

func (n NullTid) FormatCode() int16

func (*NullTid) Scan

func (n *NullTid) Scan(vr *ValueReader) error

type NullTime

NullTime represents an time.Time that may be null. NullTime implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan. It corresponds with the PostgreSQL types timestamptz, timestamp, and date.

If Valid is false then the value is NULL.

type NullTime struct {
    Time  time.Time
    Valid bool // Valid is true if Time is not NULL
}

func (NullTime) Encode

func (n NullTime) Encode(w *WriteBuf, oid Oid) error

func (NullTime) FormatCode

func (n NullTime) FormatCode() int16

func (*NullTime) Scan

func (n *NullTime) Scan(vr *ValueReader) error

type NullXid

NullXid represents a Transaction ID (Xid) that may be null. NullXid implements the Scanner and Encoder interfaces so it may be used both as an argument to Query[Row] and a destination for Scan.

If Valid is false then the value is NULL.

type NullXid struct {
    Xid   Xid
    Valid bool // Valid is true if Xid is not NULL
}

func (NullXid) Encode

func (n NullXid) Encode(w *WriteBuf, oid Oid) error

func (NullXid) FormatCode

func (n NullXid) FormatCode() int16

func (*NullXid) Scan

func (n *NullXid) Scan(vr *ValueReader) error

type Oid

Oid (Object Identifier Type) is, according to https://www.postgresql.org/docs/current/static/datatype-oid.html, used internally by PostgreSQL as a primary key for various system tables. It is currently implemented as an unsigned four-byte integer. Its definition can be found in src/include/postgres_ext.h in the PostgreSQL sources.

type Oid uint32

type PgError

PgError represents an error reported by the PostgreSQL server. See http://www.postgresql.org/docs/9.3/static/protocol-error-fields.html for detailed field description.

type PgError struct {
    Severity         string
    Code             string
    Message          string
    Detail           string
    Hint             string
    Position         int32
    InternalPosition int32
    InternalQuery    string
    Where            string
    SchemaName       string
    TableName        string
    ColumnName       string
    DataTypeName     string
    ConstraintName   string
    File             string
    Line             int32
    Routine          string
}

func (PgError) Error

func (pe PgError) Error() string

type PgType

PgType is information about PostgreSQL type and how to encode and decode it

type PgType struct {
    Name          string // name of type e.g. int4, text, date
    DefaultFormat int16  // default format (text or binary) this type will be requested in
}

type PgxScanner

PgxScanner is an interface used to decode values from the PostgreSQL server. It is used exactly the same as the Scanner interface. It simply has renamed the method.

type PgxScanner interface {
    // ScanPgx MUST check r.Type().DataType (to check by OID) or
    // r.Type().DataTypeName (to check by name) to ensure that it is scanning an
    // expected column type. It also MUST check r.Type().FormatCode before
    // decoding. It should not assume that it was called on a data type or format
    // that it understands.
    ScanPgx(r *ValueReader) error
}

type PrepareExOptions

PrepareExOptions is an option struct that can be passed to PrepareEx

type PrepareExOptions struct {
    ParameterOids []Oid
}

type PreparedStatement

PreparedStatement is a description of a prepared statement

type PreparedStatement struct {
    Name              string
    SQL               string
    FieldDescriptions []FieldDescription
    ParameterOids     []Oid
}

type ProtocolError

ProtocolError occurs when unexpected data is received from PostgreSQL

type ProtocolError string

func (ProtocolError) Error

func (e ProtocolError) Error() string

type QueryArgs

QueryArgs is a container for arguments to an SQL query. It is helpful when building SQL statements where the number of arguments is variable.

type QueryArgs []interface{}

func (*QueryArgs) Append

func (qa *QueryArgs) Append(v interface{}) string

Append adds a value to qa and returns the placeholder value for the argument. e.g. $1, $2, etc.

type ReplicationConn

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

func ReplicationConnect

func ReplicationConnect(config ConnConfig) (r *ReplicationConn, err error)

func (*ReplicationConn) CauseOfDeath

func (rc *ReplicationConn) CauseOfDeath() error

func (*ReplicationConn) Close

func (rc *ReplicationConn) Close() error

func (*ReplicationConn) CreateReplicationSlot

func (rc *ReplicationConn) CreateReplicationSlot(slotName, outputPlugin string) (err error)

Create the replication slot, using the given name and output plugin.

func (*ReplicationConn) DropReplicationSlot

func (rc *ReplicationConn) DropReplicationSlot(slotName string) (err error)

Drop the replication slot for the given name

func (*ReplicationConn) IdentifySystem

func (rc *ReplicationConn) IdentifySystem() (r *Rows, err error)

Execute the "IDENTIFY_SYSTEM" command as documented here: https://www.postgresql.org/docs/9.5/static/protocol-replication.html

This will return (if successful) a result set that has a single row that contains the systemid, current timeline, xlogpos and database name.

NOTE: Because this is a replication mode connection, we don't have type names, so the field descriptions in the result will have only Oids and no DataTypeName values

func (*ReplicationConn) IsAlive

func (rc *ReplicationConn) IsAlive() bool

func (*ReplicationConn) SendStandbyStatus

func (rc *ReplicationConn) SendStandbyStatus(k *StandbyStatus) (err error)

Send standby status to the server, which both acts as a keepalive message to the server, as well as carries the WAL position of the client, which then updates the server's replication slot position.

func (*ReplicationConn) StartReplication

func (rc *ReplicationConn) StartReplication(slotName string, startLsn uint64, timeline int64, pluginArguments ...string) (err error)

Start a replication connection, sending WAL data to the given replication receiver. This function wraps a START_REPLICATION command as documented here: https://www.postgresql.org/docs/9.5/static/protocol-replication.html

Once started, the client needs to invoke WaitForReplicationMessage() in order to fetch the WAL and standby status. Also, it is the responsibility of the caller to periodically send StandbyStatus messages to update the replication slot position.

This function assumes that slotName has already been created. In order to omit the timeline argument pass a -1 for the timeline to get the server default behavior.

func (*ReplicationConn) TimelineHistory

func (rc *ReplicationConn) TimelineHistory(timeline int) (r *Rows, err error)

Execute the "TIMELINE_HISTORY" command as documented here: https://www.postgresql.org/docs/9.5/static/protocol-replication.html

This will return (if successful) a result set that has a single row that contains the filename of the history file and the content of the history file. If called for timeline 1, typically this will generate an error that the timeline history file does not exist.

NOTE: Because this is a replication mode connection, we don't have type names, so the field descriptions in the result will have only Oids and no DataTypeName values

func (*ReplicationConn) WaitForReplicationMessage

func (rc *ReplicationConn) WaitForReplicationMessage(timeout time.Duration) (r *ReplicationMessage, err error)

Wait for a single replication message up to timeout time.

Properly using this requires some knowledge of the postgres replication mechanisms, as the client can receive both WAL data (the ultimate payload) and server heartbeat updates. The caller also must send standby status updates in order to keep the connection alive and working.

This returns pgx.ErrNotificationTimeout when there is no replication message by the specified duration.

type ReplicationMessage

The replication message wraps all possible messages from the server received during replication. At most one of the wal message or server heartbeat will be non-nil

type ReplicationMessage struct {
    WalMessage      *WalMessage
    ServerHeartbeat *ServerHeartbeat
}

type Row

Row is a convenience wrapper over Rows that is returned by QueryRow.

type Row Rows

func (*Row) Scan

func (r *Row) Scan(dest ...interface{}) (err error)

Scan works the same as (*Rows Scan) with the following exceptions. If no rows were found it returns ErrNoRows. If multiple rows are returned it ignores all but the first.

type Rows

Rows is the result set returned from *Conn.Query. Rows must be closed before the *Conn can be used again. Rows are closed by explicitly calling Close(), calling Next() until it returns false, or when a fatal error occurs.

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

func (*Rows) AfterClose

func (rows *Rows) AfterClose(f func(*Rows))

AfterClose adds f to a LILO queue of functions that will be called when rows is closed.

func (*Rows) Close

func (rows *Rows) Close()

Close closes the rows, making the connection ready for use again. It is safe to call Close after rows is already closed.

func (*Rows) Conn

func (rows *Rows) Conn() *Conn

Conn returns the *Conn this *Rows is using.

func (*Rows) Err

func (rows *Rows) Err() error

func (*Rows) Fatal

func (rows *Rows) Fatal(err error)

Fatal signals an error occurred after the query was sent to the server. It closes the rows automatically.

func (*Rows) FieldDescriptions

func (rows *Rows) FieldDescriptions() []FieldDescription

func (*Rows) Next

func (rows *Rows) Next() bool

Next prepares the next row for reading. It returns true if there is another row and false if no more rows are available. It automatically closes rows when all rows are read.

func (*Rows) Scan

func (rows *Rows) Scan(dest ...interface{}) (err error)

Scan reads the values from the current row into dest values positionally. dest can include pointers to core types, values implementing the Scanner interface, []byte, and nil. []byte will skip the decoding process and directly copy the raw bytes received from PostgreSQL. nil will skip the value entirely.

func (*Rows) Values

func (rows *Rows) Values() ([]interface{}, error)

Values returns an array of the row values

type Scanner

Deprecated: Scanner is an interface used to decode values from the PostgreSQL server. To allow types to support pgx and database/sql.Scan this interface has been deprecated in favor of PgxScanner.

type Scanner interface {
    // Scan MUST check r.Type().DataType (to check by OID) or
    // r.Type().DataTypeName (to check by name) to ensure that it is scanning an
    // expected column type. It also MUST check r.Type().FormatCode before
    // decoding. It should not assume that it was called on a data type or format
    // that it understands.
    Scan(r *ValueReader) error
}

type SerializationError

SerializationError occurs on failure to encode or decode a value

type SerializationError string

func (SerializationError) Error

func (e SerializationError) Error() string

type ServerHeartbeat

The server heartbeat is sent periodically from the server, including server status, and a reply request field

type ServerHeartbeat struct {
    // The current max wal position on the server,
    // used for lag tracking
    ServerWalEnd uint64
    // The server time, in microseconds since jan 1 2000
    ServerTime uint64
    // If 1, the server is requesting a standby status message
    // to be sent immediately.
    ReplyRequested byte
}

func (*ServerHeartbeat) String

func (s *ServerHeartbeat) String() string

func (*ServerHeartbeat) Time

func (s *ServerHeartbeat) Time() time.Time

type StandbyStatus

The standby status is the client side heartbeat sent to the postgresql server to track the client wal positions. For practical purposes, all wal positions are typically set to the same value.

type StandbyStatus struct {
    // The WAL position that's been locally written
    WalWritePosition uint64
    // The WAL position that's been locally flushed
    WalFlushPosition uint64
    // The WAL position that's been locally applied
    WalApplyPosition uint64
    // The client time in microseconds since jan 1 2000
    ClientTime uint64
    // If 1, requests the server to immediately send a
    // server heartbeat
    ReplyRequested byte
}

func NewStandbyStatus

func NewStandbyStatus(walPositions ...uint64) (status *StandbyStatus, err error)

Create a standby status struct, which sets all the WAL positions to the given wal position, and the client time to the current time. The wal positions are, in order: WalFlushPosition WalApplyPosition WalWritePosition

If only one position is provided, it will be used as the value for all 3 status fields. Note you must provide either 1 wal position, or all 3 in order to initialize the standby status.

type Tid

Tid is PostgreSQL's Tuple Identifier type.

When one does

select ctid, * from some_table;

it is the data type of the ctid hidden system column.

It is currently implemented as a pair unsigned two byte integers. Its conversion functions can be found in src/backend/utils/adt/tid.c in the PostgreSQL sources.

type Tid struct {
    BlockNumber  uint32
    OffsetNumber uint16
}

type Tx

Tx represents a database transaction.

All Tx methods return ErrTxClosed if Commit or Rollback has already been called on the Tx.

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

func (*Tx) AfterClose

func (tx *Tx) AfterClose(f func(*Tx))

AfterClose adds f to a LILO queue of functions that will be called when the transaction is closed (either Commit or Rollback).

func (*Tx) Commit

func (tx *Tx) Commit() error

Commit commits the transaction

func (*Tx) Conn

func (tx *Tx) Conn() *Conn

Conn returns the *Conn this transaction is using.

func (*Tx) CopyFrom

func (tx *Tx) CopyFrom(tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int, error)

CopyFrom delegates to the underlying *Conn

func (*Tx) CopyTo

func (tx *Tx) CopyTo(tableName string, columnNames []string, rowSrc CopyToSource) (int, error)

Deprecated. Use CopyFrom instead. CopyTo delegates to the underlying *Conn

func (*Tx) Err

func (tx *Tx) Err() error

Err returns the final error state, if any, of calling Commit or Rollback.

func (*Tx) Exec

func (tx *Tx) Exec(sql string, arguments ...interface{}) (commandTag CommandTag, err error)

Exec delegates to the underlying *Conn

func (*Tx) LargeObjects

func (tx *Tx) LargeObjects() (*LargeObjects, error)

LargeObjects returns a LargeObjects instance for the transaction.

func (*Tx) Prepare

func (tx *Tx) Prepare(name, sql string) (*PreparedStatement, error)

Prepare delegates to the underlying *Conn

func (*Tx) PrepareEx

func (tx *Tx) PrepareEx(name, sql string, opts *PrepareExOptions) (*PreparedStatement, error)

PrepareEx delegates to the underlying *Conn

func (*Tx) Query

func (tx *Tx) Query(sql string, args ...interface{}) (*Rows, error)

Query delegates to the underlying *Conn

func (*Tx) QueryRow

func (tx *Tx) QueryRow(sql string, args ...interface{}) *Row

QueryRow delegates to the underlying *Conn

func (*Tx) Rollback

func (tx *Tx) Rollback() error

Rollback rolls back the transaction. Rollback will return ErrTxClosed if the Tx is already closed, but is otherwise safe to call multiple times. Hence, a defer tx.Rollback() is safe even if tx.Commit() will be called first in a non-error condition.

func (*Tx) Status

func (tx *Tx) Status() int8

Status returns the status of the transaction from the set of pgx.TxStatus* constants.

type ValueReader

ValueReader is used by the Scanner interface to decode values.

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

func (*ValueReader) Err

func (r *ValueReader) Err() error

Err returns any error that the ValueReader has experienced

func (*ValueReader) Fatal

func (r *ValueReader) Fatal(err error)

Fatal tells r that a Fatal error has occurred

func (*ValueReader) Len

func (r *ValueReader) Len() int32

Len returns the number of unread bytes

func (*ValueReader) ReadByte

func (r *ValueReader) ReadByte() byte

func (*ValueReader) ReadBytes

func (r *ValueReader) ReadBytes(count int32) []byte

ReadBytes reads count bytes and returns as []byte

func (*ValueReader) ReadInt16

func (r *ValueReader) ReadInt16() int16

func (*ValueReader) ReadInt32

func (r *ValueReader) ReadInt32() int32

func (*ValueReader) ReadInt64

func (r *ValueReader) ReadInt64() int64

func (*ValueReader) ReadOid

func (r *ValueReader) ReadOid() Oid

func (*ValueReader) ReadString

func (r *ValueReader) ReadString(count int32) string

ReadString reads count bytes and returns as string

func (*ValueReader) ReadUint16

func (r *ValueReader) ReadUint16() uint16

func (*ValueReader) ReadUint32

func (r *ValueReader) ReadUint32() uint32

func (*ValueReader) Type

func (r *ValueReader) Type() *FieldDescription

Type returns the *FieldDescription of the value

type WalMessage

The WAL message contains WAL payload entry data

type WalMessage struct {
    // The WAL start position of this data. This
    // is the WAL position we need to track.
    WalStart uint64
    // The server wal end and server time are
    // documented to track the end position and current
    // time of the server, both of which appear to be
    // unimplemented in pg 9.5.
    ServerWalEnd uint64
    ServerTime   uint64
    // The WAL data is the raw unparsed binary WAL entry.
    // The contents of this are determined by the output
    // logical encoding plugin.
    WalData []byte
}

func (*WalMessage) ByteLag

func (w *WalMessage) ByteLag() uint64

func (*WalMessage) String

func (w *WalMessage) String() string

func (*WalMessage) Time

func (w *WalMessage) Time() time.Time

type WriteBuf

WriteBuf is used build messages to send to the PostgreSQL server. It is used by the Encoder interface when implementing custom encoders.

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

func (*WriteBuf) WriteByte

func (wb *WriteBuf) WriteByte(b byte)

func (*WriteBuf) WriteBytes

func (wb *WriteBuf) WriteBytes(b []byte)

func (*WriteBuf) WriteCString

func (wb *WriteBuf) WriteCString(s string)

func (*WriteBuf) WriteInt16

func (wb *WriteBuf) WriteInt16(n int16)

func (*WriteBuf) WriteInt32

func (wb *WriteBuf) WriteInt32(n int32)

func (*WriteBuf) WriteInt64

func (wb *WriteBuf) WriteInt64(n int64)

func (*WriteBuf) WriteUint16

func (wb *WriteBuf) WriteUint16(n uint16)

func (*WriteBuf) WriteUint32

func (wb *WriteBuf) WriteUint32(n uint32)

type Xid

Xid is PostgreSQL's Transaction ID type.

In later versions of PostgreSQL, it is the type used for the backend_xid and backend_xmin columns of the pg_stat_activity system view.

Also, when one does

select xmin, xmax, * from some_table;

it is the data type of the xmin and xmax hidden system columns.

It is currently implemented as an unsigned four byte integer. Its definition can be found in src/include/postgres_ext.h as TransactionId in the PostgreSQL sources.

type Xid uint32

Subdirectories

Name Synopsis
..
examples
chat
todo
url_shortener
stdlib Package stdlib is the compatibility layer from pgx to database/sql.