Categorygithub.com/matthewpi/pgconn
modulepackage
1.8.2
Repository: https://github.com/matthewpi/pgconn.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
34
Dependents
5
Files
2.5k SLOC

# README

CI

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

The pgconn tests require a PostgreSQL database. It will connect to the database specified in the PGX_TEST_CONN_STRING environment variable. The PGX_TEST_CONN_STRING environment variable can be a URL or DSN. In addition, the standard PG* environment variables will be respected. Consider using direnv to simplify environment variable handling.

Example Test Environment

Connect to your PostgreSQL server and run:

create database pgx_test;

Now you can run the tests:

PGX_TEST_CONN_STRING="host=/var/run/postgresql dbname=pgx_test" go test ./...

Connection and Authentication Tests

Pgconn supports multiple connection types and means of authentication. These tests are optional. They will only run if the appropriate environment variable is set. Run go test -v | grep SKIP to see if any tests are being skipped. Most developers will not need to enable these tests. See ci/setup_test.bash for an example set up if you need change authentication code.

# Packages

Package stmtcache is a cache that can be used to implement lazy prepared statements.

# Functions

Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or DSN format) to provide configuration.
Connect establishes a connection to a PostgreSQL server using config.
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.
ParseConfig builds a *Config with similar behavior to the PostgreSQL standard C library libpq.
SafeToRetry checks if the err is guaranteed to have occurred before sending any data to the server.
Timeout checks if err was was caused by a timeout.
ValidateConnectTargetSessionAttrsReadWrite is an ValidateConnectFunc that implements libpq compatible target_session_attrs=read-write.

# Structs

Batch is a collection of queries that can be sent to the PostgreSQL server in a single round-trip.
Config is the settings used to establish a connection to a PostgreSQL server.
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.
PgConn is a low-level PostgreSQL connection handle.
PgError represents an error reported by the PostgreSQL server.
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.
No description provided by the author

# Interfaces

Frontend used to receive messages from backend.

# Type aliases

No description provided by the author
BuildFrontendFunc is a function that can be used to create Frontend implementation for connection.
CommandTag is the result of an Exec function.
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.
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.
No description provided by the author