v5 – github.com/jackc/pgx/v5 Index | Examples | Files | Directories

package pgx

import "github.com/jackc/pgx/v5"

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/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.

Establishing a Connection

The primary way of establishing a connection is with `pgx.Connect`. 

conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))

The database connection string can be in URL or DSN format. Both PostgreSQL settings and pgx settings can be specified here. In addition, a config struct can be created by `ParseConfig` and modified before establishing the connection with `ConnectConfig`. 

config, err := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
if err != nil {
    // ...
}
config.Logger = log15adapter.NewLogger(log.New("module", "pgx"))

conn, err := pgx.ConnectConfig(context.Background(), config)

Connection Pool

`*pgx.Conn` represents a single connection to the database and is not concurrency safe. Use sub-package pgxpool for a concurrency safe connection pool.

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(context.Background(), "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 rows.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(context.Background(), "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(context.Background(), "delete from widgets where id=$1", 42)
if err != nil {
    return err
}
if commandTag.RowsAffected() != 1 {
    return errors.New("No row found to delete")
}

QueryFunc can be used to execute a callback function for every row. This is often easier to use than Query. 

    var sum, n int32
	_, err = conn.QueryFunc(
		context.Background(),
		"select generate_series(1,$1)",
		[]any{10},
		[]any{&n},
		func(pgx.QueryFuncRow) error {
            sum += n
			return nil
		},
	)
	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 package pgtype provides types that have a data field and a status field. They work in a similar fashion to database/sql. The second is to use a pointer to a pointer. 

var foo pgtype.Varchar
var bar *string
err := conn.QueryRow("select foo, bar from widgets where id=$1", 42).Scan(&foo, &bar)
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. The pgtype package includes many more array types for PostgreSQL types that do not directly map to native Go types.

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. In addition, pgx uses the github.com/jackc/pgtype library to support more types. See documention for that library for instructions on how to implement custom types.

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.

If pgx does cannot natively encode a type and that type is a renamed type (e.g. type MyTime time.Time) pgx will attempt to encode the underlying type. While this is usually desired behavior it can produce surprising behavior if one the underlying type and the renamed type each implement database/sql interfaces and the other implements pgx interfaces. It is recommended that this situation be avoided by implementing pgx interfaces on the renamed type.

Composite types and row values

Row values and composite types are represented as pgtype.Record (https://pkg.go.dev/github.com/jackc/pgtype?tab=doc#Record). It is possible to get values of your custom type by implementing DecodeBinary interface. Decoding into pgtype.Record first can simplify process by avoiding dealing with raw protocol directly.

For example: 

type MyType struct {
    a int      // NULL will cause decoding error
    b *string  // there can be NULL in this position in SQL
}

func (t *MyType) DecodeBinary(ci *pgtype.ConnInfo, src []byte) error {
    r := pgtype.Record{
        Fields: []pgtype.Value{&pgtype.Int4{}, &pgtype.Text{}},
    }

    if err := r.DecodeBinary(ci, src); err != nil {
        return err
    }

    if r.Status != pgtype.Present {
        return errors.New("BUG: decoding should not be called on NULL value")
    }

    a := r.Fields[0].(*pgtype.Int4)
    b := r.Fields[1].(*pgtype.Text)

    // type compatibility is checked by AssignTo
    // only lossless assignments will succeed
    if err := a.AssignTo(&t.a); err != nil {
        return err
    }

    // AssignTo also deals with null value handling
    if err := b.AssignTo(&t.b); err != nil {
        return err
    }
    return nil
}

result := MyType{}
err := conn.QueryRow(context.Background(), "select row(1, 'foo'::text)", pgx.QueryResultFormats{pgx.BinaryFormatCode}).Scan(&r)

Raw Bytes Mapping

[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified to PostgreSQL.

Transactions

Transactions are started by calling Begin. 

tx, err := conn.Begin(context.Background())
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(context.Background())

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

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

The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions. These are internally implemented with savepoints.

Use BeginTx to control the transaction mode.

BeginFunc and BeginTxFunc are variants that begin a transaction, execute a function, and commit or rollback the transaction depending on the return value of the function. These can be simpler and less error prone to use. 

err = conn.BeginFunc(context.Background(), func(tx pgx.Tx) error {
    _, err := tx.Exec(context.Background(), "insert into foo(id) values (1)")
    return err
})
if err != nil {
    return err
}

Prepared Statements

Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx includes an automatic statement cache by default. Queries run through the normal Query, QueryRow, and Exec functions are automatically prepared on first execution and the prepared statement is reused on subsequent executions. See ParseConfig for information on how to customize or disable the statement cache.

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 [][]any use CopyFromRows to wrap it in a CopyFromSource interface. Or implement CopyFromSource to avoid buffering the entire data set in memory. 

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

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

When you already have a typed array using CopyFromSlice can be more convenient. 

rows := []User{
    {"John", "Smith", 36},
    {"Jane", "Doe", 29},
}

copyCount, err := conn.CopyFrom(
    context.Background(),
    pgx.Identifier{"people"},
    []string{"first_name", "last_name", "age"},
    pgx.CopyFromSlice(len(rows), func(i int) ([]any, error) {
        return []any{rows[i].FirstName, rows[i].LastName, rows[i].Age}, nil
    }),
)

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 `Conn.WaitForNotification` method. It blocks until a notification is received or the context is canceled. 

_, err := conn.Exec(context.Background(), "listen channelname")
if err != nil {
    return nil
}

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

Logging

pgx defines a simple logger interface. Connections optionally accept a logger that satisfies this interface. Set LogLevel to control logging verbosity. Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, go.uber.org/zap, github.com/rs/zerolog, and the testing log are provided in the log directory.

Lower Level PostgreSQL Functionality

pgx is implemented on top of github.com/jackc/pgconn a lower level PostgreSQL driver. The Conn.PgConn() method can be used to access this lower layer.

PgBouncer

pgx is compatible with PgBouncer in two modes. One is when the connection has a statement cache in "describe" mode. The other is when the connection is using the simple protocol. This can be set with the PreferSimpleProtocol config option.

Index

Examples

Constants 

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

The values for log levels are chosen such that the zero value means that no log level was specified. 

const (
	TextFormatCode   = 0
	BinaryFormatCode = 1
)

PostgreSQL format codes

Variables 

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

ErrInvalidLogLevel occurs on attempt to set an invalid log level. 

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

ErrNoRows occurs when rows are expected but none are returned. 

var ErrTxClosed = errors.New("tx is closed")
var ErrTxCommitRollback = errors.New("commit unexpectedly resulted in rollback")

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.

Functions

func ScanRow 

func ScanRow(typeMap *pgtype.Map, fieldDescriptions []pgproto3.FieldDescription, values [][]byte, dest ...any) error

ScanRow decodes raw row data into dest. It can be used to scan rows read from the lower level pgconn interface.

typeMap - OID to Go type mapping. fieldDescriptions - OID and format of values values - the raw data as returned from the PostgreSQL server dest - the destination that values will be decoded into

Types

type Batch 

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

Batch queries are a way of bundling multiple queries together to avoid unnecessary network round trips. A Batch must only be sent once.

func (*Batch) Len 

func (b *Batch) Len() int

Len returns number of queries that have been queued so far.

func (*Batch) Queue 

func (b *Batch) Queue(query string, arguments ...any)

Queue queues a query to batch b. query can be an SQL query or the name of a prepared statement.

type BatchResults 

type BatchResults interface {
	// Exec reads the results from the next query in the batch as if the query has been sent with Conn.Exec.
	Exec() (pgconn.CommandTag, error)

	// Query reads the results from the next query in the batch as if the query has been sent with Conn.Query.
	Query() (Rows, error)

	// QueryRow reads the results from the next query in the batch as if the query has been sent with Conn.QueryRow.
	QueryRow() Row

	// QueryFunc reads the results from the next query in the batch as if the query has been sent with Conn.QueryFunc.
	QueryFunc(scans []any, f func(QueryFuncRow) error) (pgconn.CommandTag, error)

	// Close closes the batch operation. This must be called before the underlying connection can be used again. Any error
	// that occurred during a batch operation may have made it impossible to resyncronize the connection with the server.
	// In this case the underlying connection will have been closed. Close is safe to call multiple times.
	Close() error
}

type Conn 

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

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

func Connect 

func Connect(ctx context.Context, connString string) (*Conn, error)

Connect establishes a connection with a PostgreSQL server with a connection string. See pgconn.Connect for details.

func ConnectConfig 

func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error)

ConnectConfig establishes a connection with a PostgreSQL server with a configuration struct. connConfig must have been created by ParseConfig.

func (*Conn) Begin 

func (c *Conn) Begin(ctx context.Context) (Tx, error)

Begin starts a transaction. Unlike database/sql, the context only affects the begin command. i.e. there is no auto-rollback on context cancellation.

func (*Conn) BeginFunc 

func (c *Conn) BeginFunc(ctx context.Context, f func(Tx) error) (err error)

BeginFunc starts a transaction and calls f. If f does not return an error the transaction is committed. If f returns an error the transaction is rolled back. The context will be used when executing the transaction control statements (BEGIN, ROLLBACK, and COMMIT) but does not otherwise affect the execution of f.

func (*Conn) BeginTx 

func (c *Conn) BeginTx(ctx context.Context, txOptions TxOptions) (Tx, error)

BeginTx starts a transaction with txOptions determining the transaction mode. Unlike database/sql, the context only affects the begin command. i.e. there is no auto-rollback on context cancellation.

func (*Conn) BeginTxFunc 

func (c *Conn) BeginTxFunc(ctx context.Context, txOptions TxOptions, f func(Tx) error) (err error)

BeginTxFunc starts a transaction with txOptions determining the transaction mode and calls f. If f does not return an error the transaction is committed. If f returns an error the transaction is rolled back. The context will be used when executing the transaction control statements (BEGIN, ROLLBACK, and COMMIT) but does not otherwise affect the execution of f.

func (*Conn) Close 

func (c *Conn) Close(ctx context.Context) error

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

func (*Conn) Config 

func (c *Conn) Config() *ConnConfig

Config returns a copy of config that was used to establish this connection.

func (*Conn) CopyFrom 

func (c *Conn) CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, 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) Deallocate 

func (c *Conn) Deallocate(ctx context.Context, name string) error

Deallocate released a prepared statement

func (*Conn) Exec 

func (c *Conn) Exec(ctx context.Context, sql string, arguments ...any) (pgconn.CommandTag, 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) IsClosed 

func (c *Conn) IsClosed() bool

IsClosed reports if the connection has been closed.

func (*Conn) LoadType 

func (c *Conn) LoadType(ctx context.Context, typeName string) (*pgtype.Type, error)

LoadType inspects the database for typeName and produces a pgtype.Type suitable for registration.

func (*Conn) PgConn 

func (c *Conn) PgConn() *pgconn.PgConn

PgConn returns the underlying *pgconn.PgConn. This is an escape hatch method that allows lower level access to the PostgreSQL connection than pgx exposes.

It is strongly recommended that the connection be idle (no in-progress queries) before the underlying *pgconn.PgConn is used and the connection must be returned to the same state before any *pgx.Conn methods are again used.

func (*Conn) Ping 

func (c *Conn) Ping(ctx context.Context) error

Ping executes an empty sql statement against the *Conn If the sql returns without error, the database Ping is considered successful, otherwise, the error is returned.

func (*Conn) Prepare 

func (c *Conn) Prepare(ctx context.Context, name, sql string) (sd *pgconn.StatementDescription, 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) Query 

func (c *Conn) Query(ctx context.Context, sql string, args ...any) (Rows, error)

Query executes sql with args. It is safe to attempt to read from the returned Rows even if an error is returned. The error will be the available in rows.Err() after rows are closed. So it is allowed to ignore the error returned from Query and handle it in Rows.

Err() on the returned Rows must be checked after the Rows is closed to determine if the query executed successfully as some errors can only be detected by reading the entire response. e.g. A divide by zero error on the last row.

For extra control over how the query is executed, the types QueryExecMode, QueryResultFormats, and QueryResultFormatsByOID may be used as the first args to control exactly how the query is executed. This is rarely needed. See the documentation for those types for details.

func (*Conn) QueryFunc 

func (c *Conn) QueryFunc(ctx context.Context, sql string, args []any, scans []any, f func(QueryFuncRow) error) (pgconn.CommandTag, error)

QueryFunc executes sql with args. For each row returned by the query the values will scanned into the elements of scans and f will be called. If any row fails to scan or f returns an error the query will be aborted and the error will be returned.

Example

Code: 

{
	conn, err := pgx.Connect(context.Background(), os.Getenv("PGX_TEST_DATABASE"))
	if err != nil {
		fmt.Printf("Unable to establish connection: %v", err)
		return
	}

	var a, b int
	_, err = conn.QueryFunc(
		context.Background(),
		"select n, n * 2 from generate_series(1, $1) n",
		[]any{3},
		[]any{&a, &b},
		func(pgx.QueryFuncRow) error {
			fmt.Printf("%v, %v\n", a, b)
			return nil
		},
	)
	if err != nil {
		fmt.Printf("QueryFunc error: %v", err)
		return
	}

	// Output:
	// 1, 2
	// 2, 4
	// 3, 6
}

Output:

1, 2
2, 4
3, 6

func (*Conn) QueryRow 

func (c *Conn) QueryRow(ctx context.Context, sql string, args ...any) 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) SendBatch 

func (c *Conn) SendBatch(ctx context.Context, b *Batch) BatchResults

SendBatch sends all queued queries to the server at once. All queries are run in an implicit transaction unless explicit transaction control statements are executed. The returned BatchResults must be closed before the connection is used again.

func (*Conn) TypeMap 

func (c *Conn) TypeMap() *pgtype.Map

TypeMap returns the connection info used for this connection.

func (*Conn) WaitForNotification 

func (c *Conn) WaitForNotification(ctx context.Context) (*pgconn.Notification, error)

WaitForNotification waits for a PostgreSQL notification. It wraps the underlying pgconn notification system in a slightly more convenient form.

type ConnConfig 

type ConnConfig struct {
	pgconn.Config
	Logger   Logger
	LogLevel LogLevel

	// StatementCacheCapacity is maximum size of the statement cache used when executing a query with "cache_statement"
	// query exec mode.
	StatementCacheCapacity int

	// DescriptionCacheCapacity is the maximum size of the description cache used when executing a query with
	// "cache_describe" query exec mode.
	DescriptionCacheCapacity int

	// DefaultQueryExecMode controls the default mode for executing queries. By default pgx uses the extended protocol
	// and automatically prepares and caches prepared statements. However, this may be incompatible with proxies such as
	// PGBouncer. In this case it may be preferrable to use QueryExecModeExec or QueryExecModeSimpleProtocol. The same
	// functionality can be controlled on a per query basis by passing a QueryExecMode as the first query argument.
	DefaultQueryExecMode QueryExecMode
	// contains filtered or unexported fields
}

ConnConfig contains all the options used to establish a connection. It must be created by ParseConfig and then it can be modified. A manually initialized ConnConfig will cause ConnectConfig to panic.

func ParseConfig 

func ParseConfig(connString string) (*ConnConfig, error)

ParseConfig creates a ConnConfig from a connection string. ParseConfig handles all options that pgconn.ParseConfig does. In addition, it accepts the following options: 

default_query_exec_mode
	Possible values: "cache_statement", "cache_describe", "describe_exec", "exec", and "simple_protocol". See
	QueryExecMode constant documentation for the meaning of these values. Default: "cache_statement".

statement_cache_capacity
	The maximum size of the statement cache used when executing a query with "cache_statement" query exec mode.
	Default: 512.

description_cache_capacity
	The maximum size of the description cache used when executing a query with "cache_describe" query exec mode.
	Default: 512.

func (*ConnConfig) ConnString 

func (cc *ConnConfig) ConnString() string

ConnString returns the connection string as parsed by pgx.ParseConfig into pgx.ConnConfig.

func (*ConnConfig) Copy 

func (cc *ConnConfig) Copy() *ConnConfig

Copy returns a deep copy of the config that is safe to use and modify. The only exception is the tls.Config: according to the tls.Config docs it must not be modified after creation.

type CopyFromSource 

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() ([]any, 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
}

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

func CopyFromRows 

func CopyFromRows(rows [][]any) CopyFromSource

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

func CopyFromSlice 

func CopyFromSlice(length int, next func(int) ([]any, error)) CopyFromSource

CopyFromSlice returns a CopyFromSource interface over a dynamic func making it usable by *Conn.CopyFrom.

type Identifier 

type Identifier []string

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

func (Identifier) Sanitize 

func (ident Identifier) Sanitize() string

Sanitize returns a sanitized string safe for SQL interpolation.

type LargeObject 

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

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

io.Writer
io.Reader
io.Seeker
io.Closer

func (*LargeObject) Close 

func (o *LargeObject) Close() error

Close 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)

Truncate 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 

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

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

func (*LargeObjects) Create 

func (o *LargeObjects) Create(ctx context.Context, oid uint32) (uint32, error)

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

func (*LargeObjects) Open 

func (o *LargeObjects) Open(ctx context.Context, oid uint32, mode LargeObjectMode) (*LargeObject, error)

Open opens an existing large object with the given mode. ctx will also be used for all operations on the opened large object. 

func (o *LargeObjects) Unlink(ctx context.Context, oid uint32) error

Unlink removes a large object from the database.

type LogLevel 

type LogLevel int

LogLevel represents the pgx logging level. See LogLevel* constants for possible values.

func LogLevelFromString 

func LogLevelFromString(s string) (LogLevel, error)

LogLevelFromString converts log level string to constant

Valid levels: 

trace
debug
info
warn
error
none

func (LogLevel) String 

func (ll LogLevel) String() string

type Logger 

type Logger interface {
	// Log a message at the given level with data key/value pairs. data may be nil.
	Log(ctx context.Context, level LogLevel, msg string, data map[string]any)
}

Logger is the interface used to get logging from pgx internals.

type NamedArgs 

type NamedArgs map[string]any

NamedArgs can be used as the first argument to a query method. It will replace every '@' named placeholder with a '$' ordinal placeholder and construct the appropriate arguments.

For example, the following two queries are equivalent: 

conn.Query(ctx, "select * from widgets where foo = @foo and bar = @bar", pgx.NamedArgs{"foo": 1, "bar": 2}))
conn.Query(ctx, "select * from widgets where foo = $1 and bar = $2", 1, 2}))

func (NamedArgs) RewriteQuery 

func (na NamedArgs) RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any)

RewriteQuery implements the QueryRewriter interface.

type QueryExecMode 

type QueryExecMode int32
const (

	// Automatically prepare and cache statements. This uses the extended protocol. Queries are executed in a single
	// round trip after the statement is cached. This is the default.
	QueryExecModeCacheStatement QueryExecMode

	// Cache statement descriptions (i.e. argument and result types) and assume they do not change. This uses the
	// extended protocol. Queries are executed in a single round trip after the description is cached. If the database
	// schema is modified or the search_path is changed this may result in undetected result decoding errors.
	QueryExecModeCacheDescribe

	// Get the statement description on every execution. This uses the extended protocol. Queries require two round trips
	// to execute. It does not use prepared statements (allowing usage with most connection poolers) and is safe even
	// when the the database schema is modified concurrently.
	QueryExecModeDescribeExec

	// Assume the PostgreSQL query parameter types based on the Go type of the arguments. This uses the extended protocol
	// with text formatted parameters and results. Queries are executed in a single round trip. Type mappings can be
	// registered with pgtype.Map.RegisterDefaultPgType. Queries will be rejected that have arguments that are
	// unregistered or ambigious. e.g. A map[string]string may have the PostgreSQL type json or hstore. Modes that know
	// the PostgreSQL type can use a map[string]string directly as an argument. This mode cannot.
	QueryExecModeExec

	// Use the simple protocol. Assume the PostgreSQL query parameter types based on the Go type of the arguments.
	// Queries are executed in a single round trip. Type mappings can be registered with
	// pgtype.Map.RegisterDefaultPgType. Queries will be rejected that have arguments that are unregistered or ambigious.
	// e.g. A map[string]string may have the PostgreSQL type json or hstore. Modes that know the PostgreSQL type can use
	// a map[string]string directly as an argument. This mode cannot.
	//
	// QueryExecModeSimpleProtocol should have the user application visible behavior as QueryExecModeExec with minor
	// exceptions such as behavior when multiple result returning queries are erroneously sent in a single string.
	//
	// QueryExecModeSimpleProtocol uses client side parameter interpolation. All values are quoted and escaped. Prefer
	// QueryExecModeExec over QueryExecModeSimpleProtocol whenever possible. In general QueryExecModeSimpleProtocol
	// should only be used if connecting to a proxy server, connection pool server, or non-PostgreSQL server that does
	// not support the extended protocol.
	QueryExecModeSimpleProtocol
)

func (QueryExecMode) String 

func (m QueryExecMode) String() string

type QueryFuncRow 

type QueryFuncRow interface {
	FieldDescriptions() []pgproto3.FieldDescription

	// RawValues returns the unparsed bytes of the row values. The returned data is only valid during the current
	// function call.
	RawValues() [][]byte
}

QueryFuncRow is the argument to the QueryFunc callback function.

QueryFuncRow is an interface instead of a struct to allow tests to mock QueryFunc. However, adding a method to an interface is technically a breaking change. Because of this the QueryFuncRow interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

type QueryResultFormats 

type QueryResultFormats []int16

QueryResultFormats controls the result format (text=0, binary=1) of a query by result column position.

type QueryResultFormatsByOID 

type QueryResultFormatsByOID map[uint32]int16

QueryResultFormatsByOID controls the result format (text=0, binary=1) of a query by the result column OID.

type QueryRewriter 

type QueryRewriter interface {
	RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any)
}

QueryRewriter rewrites a query when used as the first arguments to a query method.

type Row 

type Row interface {
	// Scan works the same as Rows. with the following exceptions. If no
	// rows were found it returns ErrNoRows. If multiple rows are returned it
	// ignores all but the first.
	Scan(dest ...any) error
}

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

Row is an interface instead of a struct to allow tests to mock QueryRow. However, adding a method to an interface is technically a breaking change. Because of this the Row interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

type RowScanner 

type RowScanner interface {
	// ScanRows scans the row.
	ScanRow(rows Rows) error
}

RowScanner scans an entire row at a time into the RowScanner.

type Rows 

type Rows interface {
	// Close closes the rows, making the connection ready for use again. It is safe
	// to call Close after rows is already closed.
	Close()

	// Err returns any error that occurred while reading.
	Err() error

	// CommandTag returns the command tag from this query. It is only available after Rows is closed.
	CommandTag() pgconn.CommandTag

	FieldDescriptions() []pgproto3.FieldDescription

	// 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.
	Next() bool

	// Scan reads the values from the current row into dest values positionally.
	// dest can include pointers to core types, values implementing the Scanner
	// interface, and nil. nil will skip the value entirely. It is an error to
	// call Scan without first calling Next() and checking that it returned true.
	Scan(dest ...any) error

	// Values returns the decoded row values. As with Scan(), it is an error to
	// call Values without first calling Next() and checking that it returned
	// true.
	Values() ([]any, error)

	// RawValues returns the unparsed bytes of the row values. The returned data is only valid until the next Next
	// call or the Rows is closed.
	RawValues() [][]byte
}

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.

Once a Rows is closed the only methods that may be called are Close(), Err(), and CommandTag().

Rows is an interface instead of a struct to allow tests to mock Query. However, adding a method to an interface is technically a breaking change. Because of this the Rows interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

type ScanArgError 

type ScanArgError struct {
	ColumnIndex int
	Err         error
}

func (ScanArgError) Error 

func (e ScanArgError) Error() string

func (ScanArgError) Unwrap 

func (e ScanArgError) Unwrap() error

type Tx 

type Tx interface {
	// Begin starts a pseudo nested transaction.
	Begin(ctx context.Context) (Tx, error)

	// BeginFunc starts a pseudo nested transaction and executes f. If f does not return an err the pseudo nested
	// transaction will be committed. If it does then it will be rolled back.
	BeginFunc(ctx context.Context, f func(Tx) error) (err error)

	// Commit commits the transaction if this is a real transaction or releases the savepoint if this is a pseudo nested
	// transaction. Commit will return ErrTxClosed if the Tx is already closed, but is otherwise safe to call multiple
	// times. If the commit fails with a rollback status (e.g. the transaction was already in a broken state) then
	// ErrTxCommitRollback will be returned.
	Commit(ctx context.Context) error

	// Rollback rolls back the transaction if this is a real transaction or rolls back to the savepoint if this is a
	// pseudo nested 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. Any other failure of a real transaction will result in the connection being closed.
	Rollback(ctx context.Context) error

	CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
	SendBatch(ctx context.Context, b *Batch) BatchResults
	LargeObjects() LargeObjects

	Prepare(ctx context.Context, name, sql string) (*pgconn.StatementDescription, error)

	Exec(ctx context.Context, sql string, arguments ...any) (commandTag pgconn.CommandTag, err error)
	Query(ctx context.Context, sql string, args ...any) (Rows, error)
	QueryRow(ctx context.Context, sql string, args ...any) Row
	QueryFunc(ctx context.Context, sql string, args []any, scans []any, f func(QueryFuncRow) error) (pgconn.CommandTag, error)

	// Conn returns the underlying *Conn that on which this transaction is executing.
	Conn() *Conn
}

Tx represents a database transaction.

Tx is an interface instead of a struct to enable connection pools to be implemented without relying on internal pgx state, to support pseudo-nested transactions with savepoints, and to allow tests to mock transactions. However, adding a method to an interface is technically a breaking change. If new methods are added to Conn it may be desirable to add them to Tx as well. Because of this the Tx interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

type TxAccessMode 

type TxAccessMode string

TxAccessMode is the transaction access mode (read write or read only) 

const (
	ReadWrite TxAccessMode = "read write"
	ReadOnly  TxAccessMode = "read only"
)

Transaction access modes

type TxDeferrableMode 

type TxDeferrableMode string

TxDeferrableMode is the transaction deferrable mode (deferrable or not deferrable) 

const (
	Deferrable    TxDeferrableMode = "deferrable"
	NotDeferrable TxDeferrableMode = "not deferrable"
)

Transaction deferrable modes

type TxIsoLevel 

type TxIsoLevel string

TxIsoLevel is the transaction isolation level (serializable, repeatable read, read committed or read uncommitted) 

const (
	Serializable    TxIsoLevel = "serializable"
	RepeatableRead  TxIsoLevel = "repeatable read"
	ReadCommitted   TxIsoLevel = "read committed"
	ReadUncommitted TxIsoLevel = "read uncommitted"
)

Transaction isolation levels

type TxOptions 

type TxOptions struct {
	IsoLevel       TxIsoLevel
	AccessMode     TxAccessMode
	DeferrableMode TxDeferrableMode
}

TxOptions are transaction modes within a transaction block

Source Files

batch.go conn.go copy_from.go doc.go extended_query_builder.go large_objects.go logger.go named_args.go rows.go tx.go values.go

Directories

PathSynopsis
examples
examples/chat
examples/todo
examples/url_shortener
internal
log
log/testingadapterPackage testingadapter provides a logger that writes to a test or benchmark log.
pgconnPackage pgconn is a low-level PostgreSQL database driver.
pgconn/internal
pgproto3Package pgproto3 is a encoder and decoder of the PostgreSQL wire protocol version 3.
pgproto3/example
pgproto3/example/pgfortune
pgtypePackage pgtype converts between Go and PostgreSQL values.
pgtype/zeronullPackage zeronull contains types that automatically convert between database NULLs and Go zero values.
pgxpoolPackage pgxpool is a concurrency-safe connection pool for pgx.
pgxtestPackage pgxtest provides utilities for testing pgx and packages that integrate with pgx.
stdlibPackage stdlib is the compatibility layer from pgx to database/sql.
Version
v5.0.0-alpha.4
Published
Jun 25, 2022
Platform
darwin/amd64
Imports
18 packages
Last checked
now –

Tools for package owners.