# README
pgconn
Package pgconn is a low-level PostgreSQL database driver. It operates at nearly the same level as the C library libpq. It is primarily intended to serve as the foundation for higher level libraries such as https://github.com/jackc/pgx. Applications should handle normal queries with a higher level library and only use pgconn directly when required for low-level access to PostgreSQL functionality.
Example Usage
pgConn, err := pgconn.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
log.Fatalln("pgconn failed to connect:", err)
}
defer pgConn.Close(context.Background())
result := pgConn.ExecParams(context.Background(), "SELECT email FROM users WHERE id=$1", [][]byte{[]byte("123")}, nil, nil, nil)
for result.NextRow() {
fmt.Println("User 123 has email:", string(result.Values()[0]))
}
_, err = result.Close()
if err != nil {
log.Fatalln("failed reading result:", err)
}
Testing
See CONTRIBUTING.md for setup instructions.
# Functions
Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or keyword/value format) to provide configuration.
Connect establishes a connection to a PostgreSQL server using config.
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.
Construct created a PgConn from an already established connection to a PostgreSQL server.
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.
NewCommandTag makes a CommandTag from s.
ParseConfig builds a *Config from connString with similar behavior to the PostgreSQL standard C library libpq.
ParseConfigWithOptions builds a *Config from connString and options with similar behavior to the PostgreSQL standard C library libpq.
RegisterGSSProvider registers a GSS authentication provider.
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.
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.
# Structs
Batch is a collection of queries that can be sent to the PostgreSQL server in a single round-trip.
CancelRequestContextWatcherHandler handles canceled contexts by sending a cancel request to the server.
CloseComplete is returned by GetResults when a CloseComplete message is received.
CommandTag is the status text returned by PostgreSQL for a query.
Config is the settings used to establish a connection to a PostgreSQL server.
ConnectError is the error returned when a connection attempt fails.
DeadlineContextWatcherHandler handles canceled contexts by setting a deadline on a net.Conn.
FallbackConfig is additional settings to attempt a connection with when the primary Config fails to establish a network connection.
HijackedConn is the result of hijacking a connection.
MultiResultReader is a reader for a command that could return multiple results such as Exec or ExecBatch.
Notification is a message received from the PostgreSQL LISTEN/NOTIFY system.
ParseConfigError is the error returned when a connection string cannot be parsed.
ParseConfigOptions contains options that control how a config is built such as GetSSLPassword.
PgConn is a low-level PostgreSQL connection handle.
PgError represents an error reported by the PostgreSQL server.
Pipeline represents a connection in pipeline mode.
PipelineSync is returned by GetResults when a ReadyForQuery message is received.
Result is the saved query response that is returned by calling Read on a ResultReader.
ResultReader is a reader for the result of a single query.
# Interfaces
GSS provides GSSAPI authentication (e.g., Kerberos).
# Type aliases
BuildFrontendFunc is a function that can be used to create Frontend implementation for connection.
DialFunc is a function that can be used to connect to a PostgreSQL server.
LookupFunc is a function that can be used to lookup IPs addrs from host.
NewGSSFunc creates a GSS authentication provider, for use with RegisterGSSProvider.
Notice represents a notice response message reported by the PostgreSQL server.
NoticeHandler is a function that can handle notices received from the PostgreSQL server.
NotificationHandler is a function that can handle notifications received from the PostgreSQL server.
PgErrorHandler is a function that handles errors returned from Postgres.