Add more docs

pgconn/config.go

@@ -70,32 +70,35 @@ func NetworkAddress(host string, port uint16) (network, address string) {
 // It 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 DSN: "user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca"
+//   # Example DSN
+//   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"
+//   # Example URL
+//   postgres://jack:secret@pg.example.com:5432/mydb?sslmode=verify-ca
 //
 // 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/11/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS for more information.
 //
-// Example URL: "postgres://jack:secret@foo.example.com:5432,bar.example.com:5432/mydb"
+//   # 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 DSN:
 //
-// PGHOST
-// PGPORT
-// PGDATABASE
-// PGUSER
-// PGPASSWORD
-// PGPASSFILE
-// PGSSLMODE
-// PGSSLCERT
-// PGSSLKEY
-// PGSSLROOTCERT
-// PGAPPNAME
-// PGCONNECT_TIMEOUT
-// PGTARGETSESSIONATTRS
+// 	 PGHOST
+// 	 PGPORT
+// 	 PGDATABASE
+// 	 PGUSER
+// 	 PGPASSWORD
+// 	 PGPASSFILE
+// 	 PGSSLMODE
+// 	 PGSSLCERT
+// 	 PGSSLKEY
+// 	 PGSSLROOTCERT
+// 	 PGAPPNAME
+// 	 PGCONNECT_TIMEOUT
+// 	 PGTARGETSESSIONATTRS
 //
 // See http://www.postgresql.org/docs/11/static/libpq-envars.html for details on the meaning of environment variables.
 //

pgconn/doc.go

@@ -0,0 +1,29 @@
+// 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 DSN 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. The return readers that iterate over each query
+result. The ReadAll method reads all query results into memory.
+
+Context Support
+
+All potentially blocking operations take a context.Context. If a context is canceled while a query is in progress the
+method immediately returns. In the background a cancel request will be sent to the PostgreSQL server. If the
+cancellation fails or hangs for more than a short time (approximately 15 seconds) the connection will be closed. It is
+safe to use the connection while this background cancellation is in progress. Any calls will block until the
+cancellation and resynchronization is complete (and those calls can be aborted by a context cancellation).
+*/
+package pgconn

pgconn/pgconn.go

@@ -685,6 +685,7 @@ func (pgConn *PgConn) ExecPrepared(ctx context.Context, stmtName string, paramVa
 	return result
 }
 
+// MultiResultReader is a reader for a command that could return multiple results such as Exec or ExecBatch.
 type MultiResultReader struct {
 	pgConn                 *PgConn
 	ctx                    context.Context
@@ -696,6 +697,7 @@ type MultiResultReader struct {
 	err    error
 }
 
+// ReadAll reads all available results. Calling ReadAll is mutually exclusive with all other MultiResultReader methods.
 func (mrr *MultiResultReader) ReadAll() ([]*Result, error) {
 	var results []*Result
 
@@ -769,10 +771,12 @@ func (mrr *MultiResultReader) NextResult() bool {
 	return false
 }
 
+// ResultReader returns the current ResultReader.
 func (mrr *MultiResultReader) ResultReader() *ResultReader {
 	return mrr.rr
 }
 
+// Close closes the MultiResultReader and returns the first error that occurred during the MultiResultReader's use.
 func (mrr *MultiResultReader) Close() error {
 	for !mrr.closed {
 		_, err := mrr.receiveMessage()
@@ -784,6 +788,7 @@ func (mrr *MultiResultReader) Close() error {
 	return mrr.err
 }
 
+// ResultReader is a reader for the result of a single query.
 type ResultReader struct {
 	pgConn                 *PgConn
 	multiResultReader      *MultiResultReader
@@ -798,6 +803,7 @@ type ResultReader struct {
 	err               error
 }
 
+// Result is the saved query response that is returned by calling Read on a ResultReader.
 type Result struct {
 	FieldDescriptions []pgproto3.FieldDescription
 	Rows              [][][]byte
@@ -805,6 +811,7 @@ type Result struct {
 	Err               error
 }
 
+// Read saves the query response to a Result.
 func (rr *ResultReader) Read() *Result {
 	br := &Result{}
 
@@ -1003,7 +1010,8 @@ func (batch *Batch) ExecPrepared(stmtName string, paramValues [][]byte, paramFor
 	batch.buf = (&pgproto3.Execute{}).Encode(batch.buf)
 }
 
-// ExecBatch executes all the queries in batch in a single round-trip.
+// 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.
 func (pgConn *PgConn) ExecBatch(ctx context.Context, batch *Batch) *MultiResultReader {
 	multiResult := &MultiResultReader{
 		pgConn:                 pgConn,