Involved Source Filesauth_oauth.goauth_scram.goconfig.godefaults.go Package pgconn is a low-level PostgreSQL database driver.
pgconn provides lower level access to a PostgreSQL connection than a database/sql or pgx connection. It operates at
nearly the same level is the C library libpq.
Establishing a Connection
Use Connect to establish a connection. It accepts a connection string in URL or keyword/value format and will read the
environment for libpq style environment variables.
Executing a Query
ExecParams and ExecPrepared execute a single query. They return readers that iterate over each row. The Read method
reads all rows into memory.
Executing Multiple Queries in a Single Round Trip
Exec and ExecBatch can execute multiple queries in a single round trip. They return readers that iterate over each query
result. The ReadAll method reads all query results into memory.
Pipeline Mode
Pipeline mode allows sending queries without having read the results of previously sent queries. It allows control of
exactly how many and when network round trips occur.
Context Support
All potentially blocking operations take a context.Context. The default behavior when a context is canceled is for the
method to immediately return. In most circumstances, this will also close the underlying connection. This behavior can
be customized by using BuildContextWatcherHandler on the Config to create a ctxwatch.Handler with different behavior.
This can be especially useful when queries that are frequently canceled and the overhead of creating new connections is
a problem. DeadlineContextWatcherHandler and CancelRequestContextWatcherHandler can be used to introduce a delay before
interrupting the query in such a way as to close the connection.
The CancelRequest method may be used to request the PostgreSQL server cancel an in-progress query without forcing the
client to abort.errors.gokrb5.gopgconn.go
Package-Level Type Names (total 45, in which 35 are exported)
Batch is a collection of queries that can be sent to the PostgreSQL server in a single round-trip.buf[]byteerrerrorresultFormats[][]int16statementDescriptions[]*StatementDescription ExecParams appends an ExecParams command to the batch. See PgConn.ExecParams for parameter descriptions. ExecPrepared appends an ExecPrepared e command to the batch. See PgConn.ExecPrepared for parameter descriptions. ExecStatement appends an ExecStatement command to the batch. See PgConn.ExecPrepared for parameter descriptions.
This differs from ExecPrepared in that it takes a *StatementDescription instead of just the prepared statement name.
Because it has the *StatementDescription it can avoid the Describe Portal message that ExecPrepared must send to get
the result column descriptions.
func (*PgConn).ExecBatch(ctx context.Context, batch *Batch) *MultiResultReader
BuildFrontendFunc is a function that can be used to create Frontend implementation for connection.
CancelRequestContextWatcherHandler handles canceled contexts by sending a cancel request to the server. It also sets
a deadline on a net.Conn as a fallback. CancelRequestDelay is the delay before sending the cancel request to the server.Conn*PgConn DeadlineDelay is the delay to set on the deadline set on net.Conn when the context is canceled.cancelFinishedChanchan struct{}handleUnwatchAfterCancelCalledfunc()(*CancelRequestContextWatcherHandler) HandleCancel(context.Context)(*CancelRequestContextWatcherHandler) HandleUnwatchAfterCancel()
*CancelRequestContextWatcherHandler : github.com/jackc/pgx/v5/pgconn/ctxwatch.Handler
CloseComplete is returned by GetResults when a CloseComplete message is received.
func (*Pipeline).getResultsDeallocate() (*CloseComplete, error)
Config is the settings used to establish a connection to a PostgreSQL server. It must be created by [ParseConfig]. A
manually initialized Config will cause ConnectConfig to panic. 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. AfterNetConnect is called after the network connection, including TLS if applicable, is established but before any
PostgreSQL protocol communication. It takes the established net.Conn and returns a net.Conn that will be used in
its place. It can be used to wrap the net.Conn (e.g. for logging, diagnostics, or testing). Its functionality has
some overlap with DialFunc. However, DialFunc takes place before TLS is established and cannot be used to control
the final net.Conn used for PostgreSQL protocol communication while AfterNetConnect can. BuildContextWatcherHandler is called to create a ContextWatcherHandler for a connection. The handler is called
when a context passed to a PgConn method is canceled.BuildFrontendBuildFrontendFunc ChannelBinding is the channel_binding parameter for SCRAM-SHA-256-PLUS authentication.
Valid values: "disable", "prefer", "require". Defaults to "prefer".ConnectTimeouttime.DurationDatabasestring // e.g. net.Dialer.DialContextFallbacks[]*FallbackConfig // host (e.g. localhost) or absolute path to unix domain socket directory (e.g. /private/tmp)KerberosSpnstringKerberosSrvNamestring // e.g. net.Resolver.LookupHost MaxProtocolVersion is the maximum PostgreSQL protocol version to request from the server.
Valid values: "3.0", "3.2", "latest". Defaults to "3.0" for compatibility. MinProtocolVersion is the minimum acceptable PostgreSQL protocol version.
If the server does not support at least this version, the connection will fail.
Valid values: "3.0", "3.2", "latest". Defaults to "3.0". OAuthTokenProvider is a function that returns an OAuth token for authentication. If set, it will be used for
OAUTHBEARER SASL authentication when the server requests it. 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. OnPgError is a callback function called when a Postgres error is received by the server. The default handler will close
the connection on any FATAL errors. If you override this handler you should call the previously set handler or ensure
that you close on FATAL errors by returning false.PasswordstringPortuint16 // Run-time parameters to set on connection as session default values (e.g. search_path or application_name) // sslnegotiation=postgres or sslnegotiation=direct // nil disables TLSUserstring 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. // Used to enforce created by ParseConfig rule. Copy returns a deep copy of the config that is safe to use and modify.
The only exception is the TLSConfig field:
according to the tls.Config docs it must not be modified after creation.
func ParseConfig(connString string) (*Config, error)
func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Config, error)
func (*Config).Copy() *Config
func ConnectConfig(ctx context.Context, config *Config) (*PgConn, error)
func buildConnectOneConfigs(ctx context.Context, config *Config) ([]*connectOneConfig, []error)
func connectOne(ctx context.Context, config *Config, connectConfig *connectOneConfig, ignoreNotPreferredErr bool) (*PgConn, error)
func connectPreferred(ctx context.Context, config *Config, connectOneConfigs []*connectOneConfig) (*PgConn, []error)
ConnectError is the error returned when a connection attempt fails. // The configuration that was used in the connection attempt.errerror(*ConnectError) Error() string(*ConnectError) Unwrap() error
*ConnectError : error
DeadlineContextWatcherHandler handles canceled contexts by setting a deadline on a net.Conn.Connnet.Conn DeadlineDelay is the delay to set on the deadline set on net.Conn when the context is canceled.(*DeadlineContextWatcherHandler) HandleCancel(ctx context.Context)(*DeadlineContextWatcherHandler) HandleUnwatchAfterCancel()
*DeadlineContextWatcherHandler : github.com/jackc/pgx/v5/pgconn/ctxwatch.Handler
FallbackConfig is additional settings to attempt a connection with when the primary Config fails to establish a
network connection. It is used for TLS fallback such as sslmode=prefer and high availability (HA) connections. // host (e.g. localhost) or path to unix domain socket directory (e.g. /private/tmp)Portuint16 // nil disables TLS
HijackedConn is the result of hijacking a connection.
Due to the necessary exposure of internal implementation details, it is not covered by the semantic versioning
compatibility.Config*ConfigConnnet.ConnCustomDatamap[string]anyFrontend*pgproto3.Frontend // backend pid // parameters that have been reported by the server // key to use to send a cancel query message to the serverTxStatusbyte
func (*PgConn).Hijack() (*HijackedConn, error)
func Construct(hc *HijackedConn) (*PgConn, error)
LookupFunc is a function that can be used to lookup IPs addrs from host. Optionally an ip:port combination can be
returned in order to override the connection string's port.
MultiResultReader is a reader for a command that could return multiple results such as Exec or ExecBatch.closedboolctxcontext.ContexterrerrorpgConn*PgConnresultFormats[][]int16rr*ResultReader Data from when the batch was queued. Close closes the MultiResultReader and returns the first error that occurred during the MultiResultReader's use. NextResult returns advances the MultiResultReader to the next result and returns true if a result is available. ReadAll reads all available results. Calling ReadAll is mutually exclusive with all other MultiResultReader methods. ResultReader returns the current ResultReader.(*MultiResultReader) receiveMessage() (pgproto3.BackendMessage, error)
*MultiResultReader : io.Closer
func (*PgConn).Exec(ctx context.Context, sql string) *MultiResultReader
func (*PgConn).ExecBatch(ctx context.Context, batch *Batch) *MultiResultReader
NewGSSFunc creates a GSS authentication provider, for use with
RegisterGSSProvider.
func RegisterGSSProvider(newGSSArg NewGSSFunc)
var newGSS
NoticeHandler is a function that can handle notices received from the PostgreSQL server. Notices can be received at
any time, usually during handling of a query response. The *PgConn is provided so the handler is aware of the origin
of the notice, but it must not invoke any query method. Be aware that this is distinct from LISTEN/NOTIFY
notification.
NotificationHandler is a function that can handle notifications received from the PostgreSQL server. Notifications
can be received at any time, usually during handling of a query response. The *PgConn is provided so the handler is
aware of the origin of the notice, but it must not invoke any query method. Be aware that this is distinct from a
notice event.
ParseConfigError is the error returned when a connection string cannot be parsed. // The connection string that could not be parsed.errerrormsgstring(*ParseConfigError) Error() string(*ParseConfigError) Unwrap() error
*ParseConfigError : error
ParseConfigOptions contains options that control how a config is built such as GetSSLPassword. GetSSLPassword gets the password to decrypt a SSL client certificate. This is analogous to the libpq function
PQsetSSLKeyPassHook_OpenSSL.
func ConnectWithOptions(ctx context.Context, connString string, parseConfigOptions ParseConfigOptions) (*PgConn, error)
func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Config, error)
func configTLS(settings map[string]string, thisHost string, parseConfigOptions ParseConfigOptions) ([]*tls.Config, error)
PgConn is a low-level PostgreSQL connection handle. It is not safe for concurrent usage.bgReader*bgreader.BGReaderbgReaderStartedchan struct{}bufferingReceiveboolbufferingReceiveErrerrorbufferingReceiveMsgpgproto3.BackendMessagebufferingReceiveMuxsync.MutexcleanupDonechan struct{}config*Configconnnet.ConncontextWatcher*ctxwatch.ContextWatchercustomDatamap[string]anyfieldDescriptions[16]FieldDescriptionfrontend*pgproto3.FrontendmultiResultReaderMultiResultReader // parameters that have been reported by the serverpeekedMsgpgproto3.BackendMessage // backend pidpipelinePipeline Reusable / preallocated resources // key to use to send a cancel query message to the serverslowWriteTimer*time.Timer // One of connStatus* constantstxStatusbyte CancelRequest sends a cancel request to the PostgreSQL server. It returns an error if unable to deliver the cancel
request, but lack of an error does not ensure that the query was canceled. As specified in the documentation, there
is no way to be sure a query was canceled.
See https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-CANCELING-REQUESTS CheckConn checks the underlying connection without writing any bytes. This is currently implemented by doing a read
with a very short deadline. This can be useful because a TCP connection can be broken such that a write will appear
to succeed even though it will never actually reach the server. Reading immediately before a write will detect this
condition. If this is done immediately before sending a query it reduces the chances a query will be sent that fails
without the client knowing whether the server received it or not.
Deprecated: CheckConn is deprecated in favor of Ping. CheckConn cannot detect all types of broken connections where
the write would still appear to succeed. Prefer Ping unless on a high latency connection. CleanupDone returns a channel that will be closed after all underlying resources have been cleaned up. A closed
connection is no longer usable, but underlying resources, in particular the net.Conn, may not have finished closing
yet. This is because certain errors such as a context cancellation require that the interrupted function call return
immediately, but the error may also cause the connection to be closed. In these cases the underlying resources are
closed asynchronously.
This is only likely to be useful to connection pools. It gives them a way avoid establishing a new connection while
an old connection is still being cleaned up and thereby exceeding the maximum pool size. Close closes a connection. It is safe to call Close on an already closed connection. Close attempts a clean close by
sending the exit message to PostgreSQL. However, this could block so ctx is available to limit the time to wait. The
underlying net.Conn.Close() will always be called regardless of any other errors. Conn returns the underlying net.Conn. This rarely necessary. If the connection will be directly used for reading or
writing then SyncConn should usually be called before Conn. CopyFrom executes the copy command sql and copies all of r to the PostgreSQL server.
Note: context cancellation will only interrupt operations on the underlying PostgreSQL network connection. Reads on r
could still block. CopyTo executes the copy command sql and copies the results to w. CustomData returns a map that can be used to associate custom data with the connection. Deallocate deallocates a prepared statement.
Deallocate does not send a DEALLOCATE statement to the server. It uses the PostgreSQL Close protocol message
directly. This has slightly different behavior than executing DEALLOCATE statement.
- Deallocate can succeed in an aborted transaction.
- Deallocating a non-existent prepared statement is not an error. EscapeString escapes a string such that it can safely be interpolated into a SQL command string. It does not include
the surrounding single quotes.
The current implementation requires that standard_conforming_strings=on and client_encoding="UTF8". If these
conditions are not met an error will be returned. It is possible these restrictions will be lifted in the future. Exec executes SQL via the PostgreSQL simple query protocol. SQL may contain multiple queries. Execution is
implicitly wrapped in a transaction unless a transaction is already in progress or SQL contains transaction control
statements.
Prefer ExecParams unless executing arbitrary SQL that may contain multiple queries. ExecBatch executes all the queries in batch in a single round-trip. Execution is implicitly transactional unless a
transaction is already in progress or SQL contains transaction control statements. This is a simpler way of executing
multiple queries in a single round trip than using pipeline mode. ExecParams executes a command via the PostgreSQL extended query protocol.
sql is a SQL command string. It may only contain one query. Parameter substitution is positional using $1, $2, $3,
etc.
paramValues are the parameter values. It must be encoded in the format given by paramFormats.
paramOIDs is a slice of data type OIDs for paramValues. If paramOIDs is nil, the server will infer the data type for
all parameters. Any paramOID element that is 0 that will cause the server to infer the data type for that parameter.
ExecParams will panic if len(paramOIDs) is not 0, 1, or len(paramValues).
paramFormats is a slice of format codes determining for each paramValue column whether it is encoded in text or
binary format. If paramFormats is nil all params are text format. ExecParams will panic if
len(paramFormats) is not 0, 1, or len(paramValues).
resultFormats is a slice of format codes determining for each result column whether it is encoded in text or
binary format. If resultFormats is nil all results will be in text format.
ResultReader must be closed before PgConn can be used again. ExecPrepared enqueues the execution of a prepared statement via the PostgreSQL extended query protocol.
paramValues are the parameter values. It must be encoded in the format given by paramFormats.
paramFormats is a slice of format codes determining for each paramValue column whether it is encoded in text or
binary format. If paramFormats is nil all params are text format. ExecPrepared will panic if
len(paramFormats) is not 0, 1, or len(paramValues).
resultFormats is a slice of format codes determining for each result column whether it is encoded in text or
binary format. If resultFormats is nil all results will be in text format.
ResultReader must be closed before PgConn can be used again. ExecStatement enqueues the execution of a prepared statement via the PostgreSQL extended query protocol.
This differs from ExecPrepared in that it takes a *StatementDescription instead of the prepared statement name.
Because it has the *StatementDescription it can avoid the Describe Portal message that ExecPrepared must send to get
the result column descriptions.
paramValues are the parameter values. It must be encoded in the format given by paramFormats.
paramFormats is a slice of format codes determining for each paramValue column whether it is encoded in text or
binary format. If paramFormats is nil all params are text format. ExecPrepared will panic if len(paramFormats) is not
0, 1, or len(paramValues).
resultFormats is a slice of format codes determining for each result column whether it is encoded in text or binary
format. If resultFormats is nil all results will be in text format.
ResultReader must be closed before PgConn can be used again. Frontend returns the underlying *pgproto3.Frontend. This rarely necessary. Hijack extracts the internal connection data. pgConn must be in an idle state. SyncConn should be called immediately
before Hijack. pgConn is unusable after hijacking. Hijacking is typically only useful when using pgconn to establish
a connection, but taking complete control of the raw connection after that (e.g. a load balancer or proxy).
Due to the necessary exposure of internal implementation details, it is not covered by the semantic versioning
compatibility. IsBusy reports if the connection is busy. IsClosed reports if the connection has been closed.
CleanupDone() can be used to determine if all cleanup has been completed. PID returns the backend PID. ParameterStatus returns the value of a parameter reported by the server (e.g.
server_version). Returns an empty string for unknown parameters. Ping pings the server. This can be useful because a TCP connection can be broken such that a write will appear to
succeed even though it will never actually reach the server. Pinging immediately before sending a query reduces the
chances a query will be sent that fails without the client knowing whether the server received it or not. Prepare creates a prepared statement. If the name is empty, the anonymous prepared statement will be used. This
allows Prepare to also to describe statements without creating a server-side prepared statement.
Prepare does not send a PREPARE statement to the server. It uses the PostgreSQL Parse and Describe protocol messages
directly.
In extremely rare cases, Prepare may fail after the Parse is successful, but before the Describe is complete. In this
case, the returned error will be an error where errors.As with a *PrepareError succeeds and the *PrepareError has
ParseComplete set to true. ReceiveMessage receives one wire protocol message from the PostgreSQL server. It must only be used when the
connection is not busy. e.g. It is an error to call ReceiveMessage while reading the result of a query. The messages
are still handled by the core pgconn message handling system so receiving a NotificationResponse will still trigger
the OnNotification callback.
This is a very low level method that requires deep understanding of the PostgreSQL wire protocol to use correctly.
See https://www.postgresql.org/docs/current/protocol.html. SecretKey returns the backend secret key used to send a cancel query message to the server. StartPipeline switches the connection to pipeline mode and returns a *Pipeline. In pipeline mode requests can be sent
to the server without waiting for a response. Close must be called on the returned *Pipeline to return the connection
to normal mode. While in pipeline mode, no methods that communicate with the server may be called except
CancelRequest and Close. ctx is in effect for entire life of the *Pipeline.
Prefer ExecBatch when only sending one group of queries at once. SyncConn prepares the underlying net.Conn for direct use. PgConn may internally buffer reads or use goroutines for
background IO. This means that any direct use of the underlying net.Conn may be corrupted if a read is already
buffered or a read is in progress. SyncConn drains read buffers and stops background IO. In some cases this may
require sending a ping to the server. ctx can be used to cancel this operation. This should be called before any
operation that will use the underlying net.Conn directly. e.g. Before Conn() or Hijack().
This should not be confused with the PostgreSQL protocol Sync message. TxStatus returns the current TxStatus as reported by the server in the ReadyForQuery message.
Possible return values:
'I' - idle / not in transaction
'T' - in a transaction
'E' - in a failed transaction
See https://www.postgresql.org/docs/current/protocol-message-formats.html. WaitForNotification waits for a LISTEN/NOTIFY message to be received. It returns an error if a notification was not
received. asyncClose marks the connection as closed and asynchronously sends a cancel query message and closes the underlying
connection. enterPotentialWriteReadDeadlock must be called before a write that could deadlock if the server is simultaneously
blocked writing to us.(*PgConn) execExtendedPrefix(ctx context.Context, paramValues [][]byte) *ResultReader(*PgConn) execExtendedSuffix(result *ResultReader, statementDescription *StatementDescription, resultFormats []int16) exitPotentialWriteReadDeadlock must be called after a call to enterPotentialWriteReadDeadlock.(*PgConn) flushWithPotentialWriteReadDeadlock() error(*PgConn) getFieldDescriptionSlice(n int) []FieldDescription(*PgConn) gssAuth() error lock locks the connection. makeCommandTag makes a CommandTag. It does not retain a reference to buf or buf's underlying memory.(*PgConn) oauthAuth(ctx context.Context) error peekMessage peeks at the next message without setting up context cancellation. receiveMessage receives a message without setting up context cancellation(*PgConn) rxGSSContinue() (*pgproto3.AuthenticationGSSContinue, error)(*PgConn) rxSASLContinue() (*pgproto3.AuthenticationSASLContinue, error)(*PgConn) rxSASLFinal() (*pgproto3.AuthenticationSASLFinal, error) Perform SCRAM authentication.(*PgConn) signalMessage() chan struct{}(*PgConn) txPasswordMessage(password string) (err error)(*PgConn) unlock()
*PgConn : database/sql/driver.Pinger
func Connect(ctx context.Context, connString string) (*PgConn, error)
func ConnectConfig(ctx context.Context, config *Config) (*PgConn, error)
func ConnectWithOptions(ctx context.Context, connString string, parseConfigOptions ParseConfigOptions) (*PgConn, error)
func Construct(hc *HijackedConn) (*PgConn, error)
func github.com/jackc/pgx/v5.(*Conn).PgConn() *PgConn
func connectOne(ctx context.Context, config *Config, connectConfig *connectOneConfig, ignoreNotPreferredErr bool) (*PgConn, error)
func connectPreferred(ctx context.Context, config *Config, connectOneConfigs []*connectOneConfig) (*PgConn, []error)
func ValidateConnectTargetSessionAttrsPreferStandby(ctx context.Context, pgConn *PgConn) error
func ValidateConnectTargetSessionAttrsPrimary(ctx context.Context, pgConn *PgConn) error
func ValidateConnectTargetSessionAttrsReadOnly(ctx context.Context, pgConn *PgConn) error
func ValidateConnectTargetSessionAttrsReadWrite(ctx context.Context, pgConn *PgConn) error
func ValidateConnectTargetSessionAttrsStandby(ctx context.Context, pgConn *PgConn) error
func github.com/jackc/pgx/v5.(*Conn).bufferNotifications(_ *PgConn, n *Notification)
PgErrorHandler is a function that handles errors returned from Postgres. This function must return true to keep
the connection open. Returning false will cause the connection to be closed immediately. You should return
false on any FATAL-severity errors. This will not receive network errors. The *PgConn is provided so the handler is
aware of the origin of the error, but it must not invoke any query method.
Pipeline represents a connection in pipeline mode.
SendPrepare, SendQueryParams, SendQueryPrepared, and SendQueryStatement queue requests to the server. These requests
are not written until pipeline is flushed by Flush or Sync. Sync must be called after the last request is queued.
Requests between synchronization points are implicitly transactional unless explicit transaction control statements
have been issued.
The context the pipeline was started with is in effect for the entire life of the Pipeline.
For a deeper understanding of pipeline mode see the PostgreSQL documentation for the extended query protocol
(https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY) and the libpq pipeline mode
(https://www.postgresql.org/docs/current/libpq-pipeline-mode.html).closedboolconn*PgConnctxcontext.ContexterrerrorstatepipelineState Close closes the pipeline and returns the connection to normal mode. Flush flushes the queued requests without establishing a synchronization point. GetResults gets the next results. If results are present, results may be a *ResultReader, *StatementDescription, or
*PipelineSync. If an ErrorResponse is received from the server, results will be nil and err will be a *PgError. If no
results are available, results and err will both be nil. SendDeallocate deallocates a prepared statement. SendFlushRequest sends a request for the server to flush its output buffer.
The server flushes its output buffer automatically as a result of Sync being called,
or on any request when not in pipeline mode; this function is useful to cause the server
to flush its output buffer in pipeline mode without establishing a synchronization point.
Note that the request is not itself flushed to the server automatically; use Flush if
necessary. This copies the behavior of libpq PQsendFlushRequest. SendPipelineSync marks a synchronization point in a pipeline by sending a sync message
without flushing the send buffer. This serves as the delimiter of an implicit
transaction and an error recovery point.
Note that the request is not itself flushed to the server automatically; use Flush if
necessary. This copies the behavior of libpq PQsendPipelineSync. SendPrepare is the pipeline version of *PgConn.Prepare. SendQueryParams is the pipeline version of *PgConn.ExecParams. SendQueryPrepared is the pipeline version of *PgConn.ExecPrepared. SendQueryStatement is the pipeline version of *PgConn.ExecStatement. Sync establishes a synchronization point and flushes the queued requests.(*Pipeline) getResults() (results any, err error)(*Pipeline) getResultsDeallocate() (*CloseComplete, error)(*Pipeline) getResultsPrepare() (*StatementDescription, error)(*Pipeline) getResultsQueryParams() (*ResultReader, error)(*Pipeline) getResultsQueryPrepared() (*ResultReader, error)(*Pipeline) getResultsQueryStatement() (*ResultReader, error)(*Pipeline) getResultsSync() (*PipelineSync, error)(*Pipeline) handleUnexpectedMessage(errStr string, msg pgproto3.BackendMessage) error(*Pipeline) receiveBindComplete(errStr string) error(*Pipeline) receiveDescribedResultReader(errStr string) (*ResultReader, error)(*Pipeline) receiveMessage() (pgproto3.BackendMessage, error)(*Pipeline) receiveParseComplete(errStr string) error
*Pipeline : io.Closer
func (*PgConn).StartPipeline(ctx context.Context) *Pipeline
PipelineSync is returned by GetResults when a ReadyForQuery message is received.
func (*Pipeline).getResultsSync() (*PipelineSync, error)
// Indicates whether the error occurred after a ParseComplete message was received.errerror(*PrepareError) Error() string(*PrepareError) Unwrap() error
*PrepareError : error
errTimeout occurs when an error was caused by a timeout. Specifically, it wraps an error which is
context.Canceled, context.DeadlineExceeded, or an implementer of net.Error where Timeout() is true.errerror(*errTimeout) Error() string(*errTimeout) SafeToRetry() bool(*errTimeout) Unwrap() error
*errTimeout : error
Package-Level Functions (total 51, in which 18 are exported)
Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or keyword/value
format) to provide configuration. See documentation for [ParseConfig] for details. ctx can be used to cancel a
connect attempt.
Connect establishes a connection to a PostgreSQL server using config. config must have been constructed with
[ParseConfig]. ctx can be used to cancel a connect attempt.
If config.Fallbacks are present they will sequentially be tried in case of error establishing network connection. An
authentication error will terminate the chain of attempts (like libpq:
https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS) and be returned as the error.
Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or keyword/value
format) and ParseConfigOptions to provide additional configuration. See documentation for [ParseConfig] for details.
ctx can be used to cancel a connect attempt.
Construct created a PgConn from an already established connection to a PostgreSQL server. This is the inverse of
PgConn.Hijack. The connection must be in an idle state.
hc.Frontend is replaced by a new pgproto3.Frontend built by hc.Config.BuildFrontend.
Due to the necessary exposure of internal implementation details, it is not covered by the semantic versioning
compatibility.
ErrorResponseToPgError converts a wire protocol error message to a *PgError.
NetworkAddress converts a PostgreSQL host and port into network and address suitable for use with
net.Dial.
ParseConfig builds a *Config from connString with similar behavior to the PostgreSQL standard C library libpq. It
uses the same defaults as libpq (e.g. port=5432) and understands most PG* environment variables. ParseConfig closely
matches the parsing behavior of libpq. connString may either be in URL format or keyword = value format. See
https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be empty
to only read from the environment. If a password is not supplied it will attempt to read the .pgpass file.
# Example Keyword/Value
user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca
# Example URL
postgres://jack:secret@pg.example.com:5432/mydb?sslmode=verify-ca
The returned *Config may be modified. However, it is strongly recommended that any configuration that can be done
through the connection string be done there. In particular the fields Host, Port, TLSConfig, and Fallbacks can be
interdependent (e.g. TLSConfig needs knowledge of the host to validate the server certificate). These fields should
not be modified individually. They should all be modified or all left unchanged.
ParseConfig supports specifying multiple hosts in similar manner to libpq. Host and port may include comma separated
values that will be tried in order. This can be used as part of a high availability system. See
https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS for more information.
# Example URL
postgres://jack:secret@foo.example.com:5432,bar.example.com:5432/mydb
ParseConfig currently recognizes the following environment variable and their parameter key word equivalents passed
via database URL or keyword/value:
PGHOST
PGPORT
PGDATABASE
PGUSER
PGPASSWORD
PGPASSFILE
PGSERVICE
PGSERVICEFILE
PGSSLMODE
PGSSLCERT
PGSSLKEY
PGSSLROOTCERT
PGSSLPASSWORD
PGOPTIONS
PGAPPNAME
PGCONNECT_TIMEOUT
PGTARGETSESSIONATTRS
PGTZ
PGMINPROTOCOLVERSION
PGMAXPROTOCOLVERSION
See http://www.postgresql.org/docs/current/static/libpq-envars.html for details on the meaning of environment variables.
See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS for parameter key word names. They are
usually but not always the environment variable name downcased and without the "PG" prefix.
Important Security Notes:
ParseConfig tries to match libpq behavior with regard to PGSSLMODE. This includes defaulting to "prefer" behavior if
not set.
See http://www.postgresql.org/docs/current/static/libpq-ssl.html#LIBPQ-SSL-PROTECTION for details on what level of
security each sslmode provides.
The sslmode "prefer" (the default), sslmode "allow", and multiple hosts are implemented via the Fallbacks field of
the Config struct. If TLSConfig is manually changed it will not affect the fallbacks. For example, in the case of
sslmode "prefer" this means it will first try the main Config settings which use TLS, then it will try the fallback
which does not use TLS. This can lead to an unexpected unencrypted connection if the main TLS config is manually
changed later but the unencrypted fallback is present. Ensure there are no stale fallbacks when manually setting
TLSConfig.
Other known differences with libpq:
When multiple hosts are specified, libpq allows them to have different passwords set via the .pgpass file. pgconn
does not.
In addition, ParseConfig accepts the following options:
- servicefile.
libpq only reads servicefile from the PGSERVICEFILE environment variable. ParseConfig accepts servicefile as a
part of the connection string.
ParseConfigWithOptions builds a *Config from connString and options with similar behavior to the PostgreSQL standard
C library libpq. options contains settings that cannot be specified in a connString such as providing a function to
get the SSL password.
RegisterGSSProvider registers a GSS authentication provider. For example, if
you need to use Kerberos to authenticate with your server, add this to your
main package:
import "github.com/otan/gopgkrb5"
func init() {
pgconn.RegisterGSSProvider(func() (pgconn.GSS, error) { return gopgkrb5.NewGSS() })
}
SafeToRetry checks if the err is guaranteed to have occurred before sending any data to the server.
Timeout checks if err was caused by a timeout. To be specific, it is true if err was caused within pgconn by a
context.DeadlineExceeded or an implementer of net.Error where Timeout() is true.
ValidateConnectTargetSessionAttrsPreferStandby is a ValidateConnectFunc that implements libpq compatible
target_session_attrs=prefer-standby.
ValidateConnectTargetSessionAttrsPrimary is a ValidateConnectFunc that implements libpq compatible
target_session_attrs=primary.
ValidateConnectTargetSessionAttrsReadOnly is a ValidateConnectFunc that implements libpq compatible
target_session_attrs=read-only.
ValidateConnectTargetSessionAttrsReadWrite is a ValidateConnectFunc that implements libpq compatible
target_session_attrs=read-write.
ValidateConnectTargetSessionAttrsStandby is a ValidateConnectFunc that implements libpq compatible
target_session_attrs=standby.
buildConnectOneConfigs resolves hostnames and builds a list of connectOneConfigs to try connecting to. It returns a
slice of successfully resolved connectOneConfigs and a slice of errors. It is possible for both slices to contain
values if some hosts were successfully resolved and others were not.
configTLS uses libpq's TLS parameters to construct []*tls.Config. It is
necessary to allow returning multiple TLS configs as sslmode "allow" and
"prefer" allow fallback.
connectOne makes one connection attempt to a single host.
connectPreferred attempts to connect to the preferred host from connectOneConfigs. The connections are attempted in
order. If a connection is successful it is returned. If no connection is successful then all errors are returned. If
a connection attempt returns a [NotPreferredError], then that host will be used if no other hosts are successful.
defaultHost attempts to mimic libpq's default host. libpq uses the default unix socket location on *nix and localhost
on Windows. The default socket location is compiled into libpq. Since pgx does not have access to that default it
checks the existence of common locations.
isAbsolutePath checks if the provided value is an absolute path either
beginning with a forward slash (as on Linux-based systems) or with a capital
letter A-Z followed by a colon and a backslash, e.g., "C:\", (as on Windows).