package pgx
Import Path
github.com/jackc/pgx/v5 (on go.dev)
Dependency Relation
imports 17 packages, and imported by 2 packages
Involved Source Files
batch.go
conn.go
copy_from.go
Package pgx is a PostgreSQL database driver.
pgx provides a native PostgreSQL driver and can act as a database/sql driver. The native PostgreSQL interface is similar
to the database/sql interface while providing better speed and access to PostgreSQL specific features. Use
github.com/jackc/pgx/v5/stdlib to use pgx as a database/sql compatible driver. See that package's documentation for
details.
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] to configure settings such as tracing that cannot be configured with a connection string.
Connection Pool
[*pgx.Conn] represents a single connection to the database and is not concurrency safe. Use package
github.com/jackc/pgx/v5/pgxpool for a concurrency safe connection pool.
Query Interface
pgx implements Query in the familiar database/sql style. However, pgx provides generic functions such as CollectRows and
ForEachRow that are a simpler and safer way of processing rows than manually calling rows.Next(), rows.Scan, and
rows.Err().
CollectRows can be used collect all returned rows into a slice.
rows, _ := conn.Query(context.Background(), "select generate_series(1,$1)", 5)
numbers, err := pgx.CollectRows(rows, pgx.RowTo[int32])
if err != nil {
return err
}
// numbers => [1 2 3 4 5]
ForEachRow can be used to execute a callback function for every row. This is often easier than iterating over rows
directly.
var sum, n int32
rows, _ := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
_, err := pgx.ForEachRow(rows, []any{&n}, func() error {
sum += n
return nil
})
if err != nil {
return err
}
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")
}
PostgreSQL Data Types
pgx uses the pgtype package to converting Go values to and from PostgreSQL values. It supports many PostgreSQL types
directly and is customizable and extendable. User defined data types such as enums, domains, and composite types may
require type registration. See that package's documentation for details.
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. BeginTx also can be used to ensure a new transaction is created instead of
a pseudo nested transaction.
BeginFunc and BeginTxFunc are functions 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 = pgx.BeginFunc(context.Background(), conn, 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 err
}
notification, err := conn.WaitForNotification(context.Background())
if err != nil {
return err
}
// do something with notification
Tracing and Logging
pgx supports tracing by setting ConnConfig.Tracer.
In addition, the tracelog package provides the TraceLog type which lets a traditional logger act as a Tracer.
For debug tracing of the actual PostgreSQL wire protocol messages see github.com/jackc/pgx/v5/pgproto3.
Lower Level PostgreSQL Functionality
github.com/jackc/pgx/v5/pgconn contains a lower level PostgreSQL driver roughly at the level of libpq. pgx.Conn in
implemented on top of pgconn. The Conn.PgConn() method can be used to access this lower layer.
PgBouncer
By default pgx automatically uses prepared statements. Prepared statements are incompaptible with PgBouncer. This can be
disabled by setting a different QueryExecMode in ConnConfig.DefaultQueryExecMode.
extended_query_builder.go
large_objects.go
named_args.go
rows.go
tracer.go
tx.go
values.go
Package-Level Type Names (total 44)
Batch queries are a way of bundling multiple queries together to avoid
unnecessary network round trips. A Batch must only be sent once.
Len returns number of queries that have been queued so far.
Queue queues a query to batch b. query can be an SQL query or the name of a prepared statement.
func (*Conn).SendBatch(ctx context.Context, b *Batch) (br BatchResults)
func Tx.SendBatch(ctx context.Context, b *Batch) BatchResults
Close closes the batch operation. All unread results are read and any callback functions registered with
QueuedQuery.Query, QueuedQuery.QueryRow, or QueuedQuery.Exec will be called. If a callback function returns an
error or the batch encounters an error subsequent callback functions will not be called.
Close 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. If it returns an error subsequent calls will return the same error. Callback
functions will not be rerun.
Exec reads the results from the next query in the batch as if the query has been sent with Conn.Exec. Prefer
calling Exec on the QueuedQuery.
Query reads the results from the next query in the batch as if the query has been sent with Conn.Query. Prefer
calling Query on the QueuedQuery.
QueryRow reads the results from the next query in the batch as if the query has been sent with Conn.QueryRow.
Prefer calling QueryRow on the QueuedQuery.
BatchResults : io.Closer
func (*Conn).SendBatch(ctx context.Context, b *Batch) (br BatchResults)
func Tx.SendBatch(ctx context.Context, b *Batch) BatchResults
BatchTracer traces SendBatch.
( BatchTracer) TraceBatchEnd(ctx context.Context, conn *Conn, data TraceBatchEndData)
( BatchTracer) TraceBatchQuery(ctx context.Context, conn *Conn, data TraceBatchQueryData)
TraceBatchStart is called at the beginning of SendBatch calls. The returned context is used for the
rest of the call and will be passed to TraceBatchQuery and TraceBatchEnd.
CollectableRow is the subset of Rows methods that a RowToFunc is allowed to call.
( CollectableRow) FieldDescriptions() []pgconn.FieldDescription
( CollectableRow) RawValues() [][]byte
( CollectableRow) Scan(dest ...any) error
( CollectableRow) Values() ([]any, error)
Rows (interface)
CollectableRow : Row
func RowTo[T](row CollectableRow) (T, error)
func RowToAddrOf[T](row CollectableRow) (*T, error)
func RowToAddrOfStructByName[T](row CollectableRow) (*T, error)
func RowToAddrOfStructByNameLax[T](row CollectableRow) (*T, error)
func RowToAddrOfStructByPos[T](row CollectableRow) (*T, error)
func RowToMap(row CollectableRow) (map[string]any, error)
func RowToStructByName[T](row CollectableRow) (T, error)
func RowToStructByNameLax[T](row CollectableRow) (T, error)
func RowToStructByPos[T](row CollectableRow) (T, error)
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.
Begin starts a transaction. Unlike database/sql, the context only affects the begin command. i.e. there is no
auto-rollback on context cancellation.
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.
Close closes a connection. It is safe to call Close on a already closed
connection.
Config returns a copy of config that was used to establish this connection.
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. A pgtype.Type that supports the binary format must be registered
for the type of each column. Almost all types implemented by pgx support the binary format.
Even though enum types appear to be strings they still must be registered to use with CopyFrom. This can be done with
Conn.LoadType and pgtype.Map.RegisterType.
Deallocate released a prepared statement
DeallocateAll releases all previously prepared statements from the server and client, where it also resets the statement and description cache.
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.
IsClosed reports if the connection has been closed.
LoadType inspects the database for typeName and produces a pgtype.Type suitable for registration.
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.
Ping delegates to the underlying *pgconn.PgConn.Ping.
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.
Query sends a query to the server and returns a Rows to read the results. Only errors encountered sending the query
and initializing Rows will be returned. Err() on the returned Rows must be checked after the Rows is closed to
determine if the query executed successfully.
The returned Rows must be closed before the connection can be used again. 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. It
is allowed to ignore the error returned from Query and handle it in Rows.
It is possible for a call of FieldDescriptions on the returned Rows to return nil even if the Query call did not
return an error.
It is possible for a query to return one or more rows before encountering an error. In most cases the rows should be
collected before processing rather than processed while receiving each row. This avoids the possibility of the
application processing rows from a query that the server rejected. The CollectRows function is useful here.
An implementor of QueryRewriter may be passed as the first element of args. It can rewrite the sql and change or
replace args. For example, NamedArgs is QueryRewriter that implements named arguments.
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.
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.
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.
TypeMap returns the connection info used for this connection.
WaitForNotification waits for a PostgreSQL notification. It wraps the underlying pgconn notification system in a
slightly more convenient form.
*Conn : database/sql/driver.Pinger
func Connect(ctx context.Context, connString string) (*Conn, error)
func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error)
func ConnectWithOptions(ctx context.Context, connString string, options ParseConfigOptions) (*Conn, error)
func Rows.Conn() *Conn
func Tx.Conn() *Conn
func github.com/jackc/pgx/v5/stdlib.(*Conn).Conn() *Conn
func BatchTracer.TraceBatchEnd(ctx context.Context, conn *Conn, data TraceBatchEndData)
func BatchTracer.TraceBatchQuery(ctx context.Context, conn *Conn, data TraceBatchQueryData)
func BatchTracer.TraceBatchStart(ctx context.Context, conn *Conn, data TraceBatchStartData) context.Context
func CopyFromTracer.TraceCopyFromEnd(ctx context.Context, conn *Conn, data TraceCopyFromEndData)
func CopyFromTracer.TraceCopyFromStart(ctx context.Context, conn *Conn, data TraceCopyFromStartData) context.Context
func NamedArgs.RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any, err error)
func PrepareTracer.TracePrepareEnd(ctx context.Context, conn *Conn, data TracePrepareEndData)
func PrepareTracer.TracePrepareStart(ctx context.Context, conn *Conn, data TracePrepareStartData) context.Context
func QueryRewriter.RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any, err error)
func QueryTracer.TraceQueryEnd(ctx context.Context, conn *Conn, data TraceQueryEndData)
func QueryTracer.TraceQueryStart(ctx context.Context, conn *Conn, data TraceQueryStartData) context.Context
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.
Config pgconn.Config
AfterConnect is called after ValidateConnect. It can be used to set up the connection (e.g. Set session variables
or prepare statements). If this returns an error the connection attempt fails.
Config.BuildFrontend pgconn.BuildFrontendFunc
Config.ConnectTimeout time.Duration
Config.Database string
// e.g. net.Dialer.DialContext
Config.Fallbacks []*pgconn.FallbackConfig
// host (e.g. localhost) or absolute path to unix domain socket directory (e.g. /private/tmp)
Config.KerberosSpn string
Config.KerberosSrvName string
// e.g. net.Resolver.LookupHost
OnNotice is a callback function called when a notice response is received.
OnNotification is a callback function called when a notification from the LISTEN/NOTIFY system is received.
Config.Password string
Config.Port uint16
// Run-time parameters to set on connection as session default values (e.g. search_path or application_name)
// nil disables TLS
Config.User string
ValidateConnect is called during a connection attempt after a successful authentication with the PostgreSQL server.
It can be used to validate that the server is acceptable. If this returns an error the connection is closed and the next
fallback config is tried. This allows implementing high availability behavior such as libpq does with target_session_attrs.
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.
DescriptionCacheCapacity is the maximum size of the description cache used when executing a query with
"cache_describe" query exec mode.
StatementCacheCapacity is maximum size of the statement cache used when executing a query with "cache_statement"
query exec mode.
Tracer QueryTracer
ConnString returns the connection string as parsed by pgx.ParseConfig into pgx.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.
func ParseConfig(connString string) (*ConnConfig, error)
func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*ConnConfig, error)
func (*Conn).Config() *ConnConfig
func (*ConnConfig).Copy() *ConnConfig
func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error)
func github.com/jackc/pgx/v5/stdlib.GetConnector(config ConnConfig, opts ...stdlib.OptionOpenDB) driver.Connector
func github.com/jackc/pgx/v5/stdlib.OpenDB(config ConnConfig, opts ...stdlib.OptionOpenDB) *sql.DB
func github.com/jackc/pgx/v5/stdlib.RandomizeHostOrderFunc(ctx context.Context, connConfig *ConnConfig) error
func github.com/jackc/pgx/v5/stdlib.RegisterConnConfig(c *ConnConfig) string
ConnectTracer traces Connect and ConnectConfig.
( ConnectTracer) TraceConnectEnd(ctx context.Context, data TraceConnectEndData)
TraceConnectStart is called at the beginning of Connect and ConnectConfig calls. The returned context is used for
the rest of the call and will be passed to TraceConnectEnd.
CopyFromSource is the interface used by *Conn.CopyFrom as the source for copy data.
Err returns any error that has been encountered by the CopyFromSource. If
this is not nil *Conn.CopyFrom will abort the copy.
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.
Values returns the values for the current row.
Rows (interface)
func CopyFromRows(rows [][]any) CopyFromSource
func CopyFromSlice(length int, next func(int) ([]any, error)) CopyFromSource
func (*Conn).CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
func Tx.CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
CopyFromTracer traces CopyFrom.
( CopyFromTracer) TraceCopyFromEnd(ctx context.Context, conn *Conn, data TraceCopyFromEndData)
TraceCopyFromStart is called at the beginning of CopyFrom calls. The returned context is used for the
rest of the call and will be passed to TraceCopyFromEnd.
ExtendedQueryBuilder is used to choose the parameter formats, to format the parameters and to choose the result
formats for an extended query.
ParamFormats []int16
ParamValues [][]byte
ResultFormats []int16
Build sets ParamValues, ParamFormats, and ResultFormats for use with *PgConn.ExecParams or *PgConn.ExecPrepared. If
sd is nil then QueryExecModeExec behavior will be used.
Identifier a PostgreSQL identifier or name. Identifiers can be composed of
multiple parts such as ["schema", "table"] or ["table", "column"].
Sanitize returns a sanitized string safe for SQL interpolation.
func (*Conn).CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
func Tx.CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
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
Close the large object descriptor.
Read reads up to len(p) bytes into p returning the number of bytes read.
Seek moves the current location pointer to the new location specified by offset.
Tell returns the current read or write location of the large object descriptor.
Truncate the large object to size.
Write writes p to the large object and returns the number of bytes written and an error if not all of p was written.
*LargeObject : internal/bisect.Writer
*LargeObject : io.Closer
*LargeObject : io.ReadCloser
*LargeObject : io.Reader
*LargeObject : io.ReadSeekCloser
*LargeObject : io.ReadSeeker
*LargeObject : io.ReadWriteCloser
*LargeObject : io.ReadWriter
*LargeObject : io.ReadWriteSeeker
*LargeObject : io.Seeker
*LargeObject : io.WriteCloser
*LargeObject : io.Writer
*LargeObject : io.WriteSeeker
func (*LargeObjects).Open(ctx context.Context, oid uint32, mode LargeObjectMode) (*LargeObject, error)
func (*LargeObjects).Open(ctx context.Context, oid uint32, mode LargeObjectMode) (*LargeObject, error)
const LargeObjectModeRead
const LargeObjectModeWrite
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
Create creates a new large object. If oid is zero, the server assigns an unused OID.
Open opens an existing large object with the given mode. ctx will also be used for all operations on the opened large
object.
Unlink removes a large object from the database.
func Tx.LargeObjects() LargeObjects
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)
RewriteQuery implements the QueryRewriter interface.
NamedArgs : QueryRewriter
ParseConfigOptions contains options that control how a config is built such as getsslpassword.
ParseConfigOptions pgconn.ParseConfigOptions
GetSSLPassword gets the password to decrypt a SSL client certificate. This is analogous to the the libpq function
PQsetSSLKeyPassHook_OpenSSL.
func ConnectWithOptions(ctx context.Context, connString string, options ParseConfigOptions) (*Conn, error)
func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*ConnConfig, error)
PrepareTracer traces Prepare.
( PrepareTracer) TracePrepareEnd(ctx context.Context, conn *Conn, data TracePrepareEndData)
TracePrepareStart is called at the beginning of Prepare calls. The returned context is used for the
rest of the call and will be passed to TracePrepareEnd.
( QueryExecMode) String() string
QueryExecMode : github.com/ChrisTrenkamp/goxpath/tree.Result
QueryExecMode : fmt.Stringer
const QueryExecModeCacheDescribe
const QueryExecModeCacheStatement
const QueryExecModeDescribeExec
const QueryExecModeExec
const QueryExecModeSimpleProtocol
QueryResultFormats controls the result format (text=0, binary=1) of a query by result column position.
QueryResultFormatsByOID controls the result format (text=0, binary=1) of a query by the result column OID.
QueryRewriter rewrites a query when used as the first arguments to a query method.
( QueryRewriter) RewriteQuery(ctx context.Context, conn *Conn, sql string, args []any) (newSQL string, newArgs []any, err error)
NamedArgs
QueryTracer traces Query, QueryRow, and Exec.
( QueryTracer) TraceQueryEnd(ctx context.Context, conn *Conn, data TraceQueryEndData)
TraceQueryStart is called at the beginning of Query, QueryRow, and Exec calls. The returned context is used for the
rest of the call and will be passed to TraceQueryEnd.
QueuedQuery is a query that has been queued for execution via a Batch.
Exec sets fn to be called when the response to qq is received.
Query sets fn to be called when the response to qq is received.
Query sets fn to be called when the response to qq is received.
func (*Batch).Queue(query string, arguments ...any) *QueuedQuery
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.
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.
CollectableRow (interface)
Rows (interface)
*database/sql.Row
*database/sql.Rows
gorm.io/gorm.Rows (interface)
func BatchResults.QueryRow() Row
func (*Conn).QueryRow(ctx context.Context, sql string, args ...any) Row
func Tx.QueryRow(ctx context.Context, sql string, args ...any) Row
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.
Close closes the rows, making the connection ready for use again. It is safe
to call Close after rows is already closed.
CommandTag returns the command tag from this query. It is only available after Rows is closed.
Conn returns the underlying *Conn on which the query was executed. This may return nil if Rows did not come from a
*Conn (e.g. if it was created by RowsFromResultReader)
Err returns any error that occurred while reading. Err must only be called after the Rows is closed (either by
calling Close or by Next returning false). If it is called early it may return nil even if there was an error
executing the query.
FieldDescriptions returns the field descriptions of the columns. It may return nil. In particular this can occur
when there was an error executing the query.
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.
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.
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.
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.
Rows : CollectableRow
Rows : CopyFromSource
Rows : Row
func RowsFromResultReader(typeMap *pgtype.Map, resultReader *pgconn.ResultReader) Rows
func BatchResults.Query() (Rows, error)
func (*Conn).Query(ctx context.Context, sql string, args ...any) (Rows, error)
func Tx.Query(ctx context.Context, sql string, args ...any) (Rows, error)
func CollectOneRow[T](rows Rows, fn RowToFunc[T]) (T, error)
func CollectRows[T](rows Rows, fn RowToFunc[T]) ([]T, error)
func ForEachRow(rows Rows, scans []any, fn func() error) (pgconn.CommandTag, error)
func RowScanner.ScanRow(rows Rows) error
RowScanner scans an entire row at a time into the RowScanner.
ScanRows scans the row.
Type Parameters:
T: any
RowToFunc is a function that scans or otherwise converts row to a T.
func CollectOneRow[T](rows Rows, fn RowToFunc[T]) (T, error)
func CollectRows[T](rows Rows, fn RowToFunc[T]) ([]T, error)
ColumnIndex int
Err error
( ScanArgError) Error() string
( ScanArgError) Unwrap() error
ScanArgError : error
Err error
func BatchTracer.TraceBatchEnd(ctx context.Context, conn *Conn, data TraceBatchEndData)
Args []any
CommandTag pgconn.CommandTag
Err error
SQL string
func BatchTracer.TraceBatchQuery(ctx context.Context, conn *Conn, data TraceBatchQueryData)
Batch *Batch
func BatchTracer.TraceBatchStart(ctx context.Context, conn *Conn, data TraceBatchStartData) context.Context
Conn *Conn
Err error
func ConnectTracer.TraceConnectEnd(ctx context.Context, data TraceConnectEndData)
ConnConfig *ConnConfig
func ConnectTracer.TraceConnectStart(ctx context.Context, data TraceConnectStartData) context.Context
CommandTag pgconn.CommandTag
Err error
func CopyFromTracer.TraceCopyFromEnd(ctx context.Context, conn *Conn, data TraceCopyFromEndData)
ColumnNames []string
TableName Identifier
func CopyFromTracer.TraceCopyFromStart(ctx context.Context, conn *Conn, data TraceCopyFromStartData) context.Context
AlreadyPrepared bool
Err error
func PrepareTracer.TracePrepareEnd(ctx context.Context, conn *Conn, data TracePrepareEndData)
Name string
SQL string
func PrepareTracer.TracePrepareStart(ctx context.Context, conn *Conn, data TracePrepareStartData) context.Context
CommandTag pgconn.CommandTag
Err error
func QueryTracer.TraceQueryEnd(ctx context.Context, conn *Conn, data TraceQueryEndData)
Args []any
SQL string
func QueryTracer.TraceQueryStart(ctx context.Context, conn *Conn, data TraceQueryStartData) context.Context
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.
Begin starts a pseudo nested transaction.
Commit commits the transaction if this is a real transaction or releases the savepoint if this is a pseudo nested
transaction. Commit will return an error where errors.Is(ErrTxClosed) is true 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 an error where errors.Is(ErrTxCommitRollback) is true will be returned.
Conn returns the underlying *Conn that on which this transaction is executing.
( Tx) CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
( Tx) Exec(ctx context.Context, sql string, arguments ...any) (commandTag pgconn.CommandTag, err error)
( Tx) LargeObjects() LargeObjects
( Tx) Prepare(ctx context.Context, name, sql string) (*pgconn.StatementDescription, error)
( Tx) Query(ctx context.Context, sql string, args ...any) (Rows, error)
( Tx) QueryRow(ctx context.Context, sql string, args ...any) Row
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 an error where errors.Is(ErrTxClosed) is true 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.
( Tx) SendBatch(ctx context.Context, b *Batch) BatchResults
func (*Conn).Begin(ctx context.Context) (Tx, error)
func (*Conn).BeginTx(ctx context.Context, txOptions TxOptions) (Tx, error)
func Tx.Begin(ctx context.Context) (Tx, error)
TxAccessMode is the transaction access mode (read write or read only)
const ReadOnly
const ReadWrite
TxDeferrableMode is the transaction deferrable mode (deferrable or not deferrable)
const Deferrable
const NotDeferrable
TxIsoLevel is the transaction isolation level (serializable, repeatable read, read committed or read uncommitted)
const ReadCommitted
const ReadUncommitted
const RepeatableRead
const Serializable
TxOptions are transaction modes within a transaction block
AccessMode TxAccessMode
BeginQuery is the SQL query that will be executed to begin the transaction. This allows using non-standard syntax
such as BEGIN PRIORITY HIGH with CockroachDB. If set this will override the other settings.
DeferrableMode TxDeferrableMode
IsoLevel TxIsoLevel
func BeginTxFunc(ctx context.Context, db interface{BeginTx(ctx context.Context, txOptions TxOptions) (Tx, error)}, txOptions TxOptions, fn func(Tx) error) (err error)
func (*Conn).BeginTx(ctx context.Context, txOptions TxOptions) (Tx, error)
Package-Level Functions (total 23)
BeginFunc calls Begin on db and then calls fn. If fn does not return an error then it calls Commit on db. If fn
returns an error it calls Rollback on db. The context will be used when executing the transaction control statements
(BEGIN, ROLLBACK, and COMMIT) but does not otherwise affect the execution of fn.
BeginTxFunc calls BeginTx on db and then calls fn. If fn does not return an error then it calls Commit on db. If fn
returns an error it calls Rollback on db. The context will be used when executing the transaction control statements
(BEGIN, ROLLBACK, and COMMIT) but does not otherwise affect the execution of fn.
Type Parameters:
T: any
CollectOneRow calls fn for the first row in rows and returns the result. If no rows are found returns an error where errors.Is(ErrNoRows) is true.
CollectOneRow is to CollectRows as QueryRow is to Query.
Type Parameters:
T: any
CollectRows iterates through rows, calling fn for each row, and collecting the results into a slice of T.
Connect establishes a connection with a PostgreSQL server with a connection string. See
pgconn.Connect for details.
ConnectConfig establishes a connection with a PostgreSQL server with a configuration struct.
connConfig must have been created by ParseConfig.
ConnectWithOptions behaves exactly like Connect with the addition of options. At the present options is only used to
provide a GetSSLPassword function.
CopyFromRows returns a CopyFromSource interface over the provided rows slice
making it usable by *Conn.CopyFrom.
CopyFromSlice returns a CopyFromSource interface over a dynamic func
making it usable by *Conn.CopyFrom.
ForEachRow iterates through rows. For each row it scans into the elements of scans and calls fn. If any row
fails to scan or fn returns an error the query will be aborted and the error will be returned. Rows will be closed
when ForEachRow returns.
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.
ParseConfigWithOptions behaves exactly as ParseConfig does with the addition of options. At the present options is
only used to provide a GetSSLPassword function.
RowsFromResultReader returns a Rows that will read from values resultReader and decode with typeMap. It can be used
to read from the lower level pgconn interface.
Type Parameters:
T: any
RowTo returns a T scanned from row.
Type Parameters:
T: any
RowTo returns a the address of a T scanned from row.
Type Parameters:
T: any
RowToAddrOfStructByName returns the address of a T scanned from row. T must be a struct. T must have the same number
of named public fields as row has fields. The row and T fields will by matched by name. The match is
case-insensitive. The database column name can be overridden with a "db" struct tag. If the "db" struct tag is "-"
then the field will be ignored.
Type Parameters:
T: any
RowToAddrOfStructByNameLax returns the address of a T scanned from row. T must be a struct. T must have greater than or
equal number of named public fields as row has fields. The row and T fields will by matched by name. The match is
case-insensitive. The database column name can be overridden with a "db" struct tag. If the "db" struct tag is "-"
then the field will be ignored.
Type Parameters:
T: any
RowToAddrOfStructByPos returns the address of a T scanned from row. T must be a struct. T must have the same number a
public fields as row has fields. The row and T fields will by matched by position. If the "db" struct tag is "-" then
the field will be ignored.
RowToMap returns a map scanned from row.
Type Parameters:
T: any
RowToStructByName returns a T scanned from row. T must be a struct. T must have the same number of named public
fields as row has fields. The row and T fields will by matched by name. The match is case-insensitive. The database
column name can be overridden with a "db" struct tag. If the "db" struct tag is "-" then the field will be ignored.
Type Parameters:
T: any
RowToStructByNameLax returns a T scanned from row. T must be a struct. T must have greater than or equal number of named public
fields as row has fields. The row and T fields will by matched by name. The match is case-insensitive. The database
column name can be overridden with a "db" struct tag. If the "db" struct tag is "-" then the field will be ignored.
Type Parameters:
T: any
RowToStructByPos returns a T scanned from row. T must be a struct. T must have the same number a public fields as row
has fields. The row and T fields will by matched by position. If the "db" struct tag is "-" then the field will be
ignored.
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
Package-Level Variables (total 3)
ErrNoRows occurs when rows are expected but none are returned.
var ErrTxClosed error
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.
Package-Level Constants (total 17)
PostgreSQL format codes
Transaction deferrable modes
const LargeObjectModeRead LargeObjectMode = 262144 const LargeObjectModeWrite LargeObjectMode = 131072
Transaction deferrable modes
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.
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.
Get the statement description on every execution. This uses the extended protocol. Queries require two round trips
to execute. It does not use named prepared statements. But it does use the unnamed prepared statement to get the
statement description on the first round trip and then uses it to execute the query on the second round trip. This
may cause problems with connection poolers that switch the underlying connection between round trips. It is safe
even when the the database schema is modified concurrently.
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.
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.
Transaction isolation levels
Transaction access modes
Transaction isolation levels
Transaction access modes
Transaction isolation levels
Transaction isolation levels
PostgreSQL format codes
 |
The pages are generated with Golds v0.6.7. (GOOS=linux GOARCH=amd64) Golds is a Go 101 project developed by Tapir Liu. PR and bug reports are welcome and can be submitted to the issue list. Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds. |