GOMODULES
/
pgx
mirror of https://github.com/jackc/pgx.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs for first prerelease of v4

pull/586/head v4.0.0-pre1
Jack Christensen 2019-06-29 13:59:05 -05:00
parent a99cd7758a
commit da16226e0a
4 changed files with 69 additions and 498 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

374
CHANGELOG.md
View File

@ -1,357 +1,17 @@
# 3.3.0 (December 1, 2018)
## Features
* Add CopyFromReader and CopyToWriter (Murat Kabilov)
* Add MacaddrArray (Anthony Regeda)
* Add float types to FieldDescription.Type (David Yamnitsky)
* Add CheckedOutConnections helper method (MOZGIII)
* Add host query parameter to support Unix sockets (Jörg Thalheim)
* Custom cancelation hook for use with PostgreSQL-like databases (James Hartig)
* Added LastStmtSent for safe retry logic (James Hartig)
## Fixes
* Do not silently ignore assign NULL to \*string
* Fix issue with JSON and driver.Valuer conversion
* Fix race with stdlib Driver.configs Open (Greg Curtis)
## Changes
* Connection pool uses connections in queue order instead of stack. This
minimized the time any connection is idle vs. any other connection.
(Anthony Regeda)
* FieldDescription.Modifier is int32 instead of uint32
* tls: stop sending ssl_renegotiation_limit in startup message (Tejas Manohar)
# 3.2.0 (August 7, 2018)
## Features
* Support sslkey, sslcert, and sslrootcert URI params (Sean Chittenden)
* Allow any scheme in ParseURI (for convenience with cockroachdb) (Sean Chittenden)
* Add support for domain types
* Add zerolog logging adaptor (Justin Reagor)
* Add driver.Connector support / Go 1.10 support (James Lawrence)
* Allow nested database/sql/driver.Drivers (Jackson Owens)
* Support int64 and uint64 numeric array (Anthony Regeda)
* Add nul support to pgtype.Bool (Tarik Demirci)
* Add types to decode error messages (Damir Vandic)
## Fixes
* Fix Rows.Values returning same value for multiple columns of same complex type
* Fix StartReplication() syntax (steampunkcoder)
* Fix precision loss for test format geometric types
* Allows scanning jsonb column into `*json.RawMessage`
* Allow recovery to savepoint in failed transaction
* Fix deadlock when CopyFromSource panics
* Include PreferSimpleProtocol in config Merge (Murat Kabilov)
## Changes
* pgtype.JSON(B).Value now returns []byte instead of string. This allows
database/sql to scan json(b) into \*json.RawMessage. This is a tiny behavior
change, but database/sql Scan should automatically convert []byte to string, so
there shouldn't be any incompatibility.
# 3.1.0 (January 15, 2018)
## Features
* Add QueryEx, QueryRowEx, ExecEx, and RollbackEx to Tx
* Add more ColumnType support (Timothée Peignier)
* Add UUIDArray type (Kelsey Francis)
* Add zap log adapter (Kelsey Francis)
* Add CreateReplicationSlotEx that consistent_point and snapshot_name (Mark Fletcher)
* Add BeginBatch to Tx (Gaspard Douady)
* Support CrateDB (Felix Geisendörfer)
* Allow use of logrus logger with fields configured (André Bierlein)
* Add array of enum support
* Add support for bit type
* Handle timeout parameters (Timothée Peignier)
* Allow overriding connection info (James Lawrence)
* Add support for bpchar type (Iurii Krasnoshchok)
* Add ConnConfig.PreferSimpleProtocol
## Fixes
* Fix numeric EncodeBinary bug (Wei Congrui)
* Fix logrus updated package name (Damir Vandic)
* Fix some invalid one round trip execs failing to return non-nil error. (Kelsey Francis)
* Return ErrClosedPool when Acquire() with closed pool (Mike Graf)
* Fix decoding row with same type values
* Always return non-nil \*Rows from Query to fix QueryRow (Kelsey Francis)
* Fix pgtype types that can Set database/sql/driver.driver.Valuer
* Prefix types in namespaces other than pg_catalog or public (Kelsey Francis)
* Fix incomplete selects during batch (Gaspard Douady and Jack Christensen)
* Support nil pointers to value implementing driver.Valuer
* Fix time logging for QueryEx
* Fix ranges with text format where end is unbounded
* Detect erroneous JSON(B) encoding
* Fix missing interval mapping
* ConnPool begin should not retry if ctx is done (Gaspard Douady)
* Fix reading interrupted messages could break connection
* Return error on unknown oid while decoding record instead of panic (Iurii Krasnoshchok)
## Changes
* Align sslmode "require" more closely to libpq (Johan Brandhorst)
# 3.0.1 (August 12, 2017)
## Fixes
* Fix compilation on 32-bit platform
* Fix invalid MarshalJSON of types with status Undefined
* Fix pid logging
# 3.0.0 (July 24, 2017)
## Changes
* Pid to PID in accordance with Go naming conventions.
* Conn.Pid changed to accessor method Conn.PID()
* Conn.SecretKey removed
* Remove Conn.TxStatus
* Logger interface reduced to single Log method.
* Replace BeginIso with BeginEx. BeginEx adds support for read/write mode and deferrable mode.
* Transaction isolation level constants are now typed strings instead of bare strings.
* Conn.WaitForNotification now takes context.Context instead of time.Duration for cancellation support.
* Conn.WaitForNotification no longer automatically pings internally every 15 seconds.
* ReplicationConn.WaitForReplicationMessage now takes context.Context instead of time.Duration for cancellation support.
* Reject scanning binary format values into a string (e.g. binary encoded timestamptz to string). See https://github.com/jackc/pgx/issues/219 and https://github.com/jackc/pgx/issues/228
* No longer can read raw bytes of any value into a []byte. Use pgtype.GenericBinary if this functionality is needed.
* Remove CopyTo (functionality is now in CopyFrom)
* OID constants moved from pgx to pgtype package
* Replaced Scanner, Encoder, and PgxScanner interfaces with pgtype system
* Removed ValueReader
* ConnPool.Close no longer waits for all acquired connections to be released. Instead, it immediately closes all available connections, and closes acquired connections when they are released in the same manner as ConnPool.Reset.
* Removed Rows.Fatal(error)
* Removed Rows.AfterClose()
* Removed Rows.Conn()
* Removed Tx.AfterClose()
* Removed Tx.Conn()
* Use Go casing convention for OID, UUID, JSON(B), ACLItem, CID, TID, XID, and CIDR
* Replaced stdlib.OpenFromConnPool with DriverConfig system
## Features
* Entirely revamped pluggable type system that supports approximately 60 PostgreSQL types.
* Types support database/sql interfaces and therefore can be used with other drivers
* Added context methods supporting cancellation where appropriate
* Added simple query protocol support
* Added single round-trip query mode
* Added batch query operations
* Added OnNotice
* github.com/pkg/errors used where possible for errors
* Added stdlib.DriverConfig which directly allows full configuration of underlying pgx connections without needing to use a pgx.ConnPool
* Added AcquireConn and ReleaseConn to stdlib to allow acquiring a connection from a database/sql connection.
# 2.11.0 (June 5, 2017)
## Fixes
* Fix race with concurrent execution of stdlib.OpenFromConnPool (Terin Stock)
## Features
* .pgpass support (j7b)
* Add missing CopyFrom delegators to Tx and ConnPool (Jack Christensen)
* Add ParseConnectionString (James Lawrence)
## Performance
* Optimize HStore encoding (René Kroon)
# 2.10.0 (March 17, 2017)
## Fixes
* database/sql driver created through stdlib.OpenFromConnPool closes connections when requested by database/sql rather than release to underlying connection pool.
# 2.11.0 (June 5, 2017)
## Fixes
* Fix race with concurrent execution of stdlib.OpenFromConnPool (Terin Stock)
## Features
* .pgpass support (j7b)
* Add missing CopyFrom delegators to Tx and ConnPool (Jack Christensen)
* Add ParseConnectionString (James Lawrence)
## Performance
* Optimize HStore encoding (René Kroon)
# 2.10.0 (March 17, 2017)
## Fixes
* Oid underlying type changed to uint32, previously it was incorrectly int32 (Manni Wood)
* Explicitly close checked-in connections on ConnPool.Reset, previously they were closed by GC
## Features
* Add xid type support (Manni Wood)
* Add cid type support (Manni Wood)
* Add tid type support (Manni Wood)
* Add "char" type support (Manni Wood)
* Add NullOid type (Manni Wood)
* Add json/jsonb binary support to allow use with CopyTo
* Add named error ErrAcquireTimeout (Alexander Staubo)
* Add logical replication decoding (Kris Wehner)
* Add PgxScanner interface to allow types to simultaneously support database/sql and pgx (Jack Christensen)
* Add CopyFrom with schema support (Jack Christensen)
## Compatibility
* jsonb now defaults to binary format. This means passing a []byte to a jsonb column will no longer work.
* CopyTo is now deprecated but will continue to work.
# 2.9.0 (August 26, 2016)
## Fixes
* Fix *ConnPool.Deallocate() not deleting prepared statement from map
* Fix stdlib not logging unprepared query SQL (Krzysztof Dryś)
* Fix Rows.Values() with varchar binary format
* Concurrent ConnPool.Acquire calls with Dialer timeouts now timeout in the expected amount of time (Konstantin Dzreev)
## Features
* Add CopyTo
* Add PrepareEx
* Add basic record to []interface{} decoding
* Encode and decode between all Go and PostgreSQL integer types with bounds checking
* Decode inet/cidr to net.IP
* Encode/decode [][]byte to/from bytea[]
* Encode/decode named types whose underlying types are string, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64
## Performance
* Substantial reduction in memory allocations
# 2.8.1 (March 24, 2016)
## Features
* Scan accepts nil argument to ignore a column
## Fixes
* Fix compilation on 32-bit architecture
* Fix Tx.status not being set on error on Commit
* Fix Listen/Unlisten with special characters
# 2.8.0 (March 18, 2016)
## Fixes
* Fix unrecognized commit failure
* Fix msgReader.rxMsg bug when msgReader already has error
* Go float64 can no longer be encoded to a PostgreSQL float4
* Fix connection corruption when query with error is closed early
## Features
This release adds multiple extension points helpful when wrapping pgx with
custom application behavior. pgx can now use custom types designed for the
standard database/sql package such as
[github.com/shopspring/decimal](https://github.com/shopspring/decimal).
* Add *Tx.AfterClose() hook
* Add *Tx.Conn()
* Add *Tx.Status()
* Add *Tx.Err()
* Add *Rows.AfterClose() hook
* Add *Rows.Conn()
* Add *Conn.SetLogger() to allow changing logger
* Add *Conn.SetLogLevel() to allow changing log level
* Add ConnPool.Reset method
* Add support for database/sql.Scanner and database/sql/driver.Valuer interfaces
* Rows.Scan errors now include which argument caused error
* Add Encode() to allow custom Encoders to reuse internal encoding functionality
* Add Decode() to allow customer Decoders to reuse internal decoding functionality
* Add ConnPool.Prepare method
* Add ConnPool.Deallocate method
* Add Scan to uint32 and uint64 (utrack)
* Add encode and decode to []uint16, []uint32, and []uint64 (Max Musatov)
## Performance
* []byte skips encoding/decoding
# 2.7.1 (October 26, 2015)
* Disable SSL renegotiation
# 2.7.0 (October 16, 2015)
* Add RuntimeParams to ConnConfig
* ParseURI extracts RuntimeParams
* ParseDSN extracts RuntimeParams
* ParseEnvLibpq extracts PGAPPNAME
* Prepare is now idempotent
* Rows.Values now supports oid type
* ConnPool.Release automatically unlistens connections (Joseph Glanville)
* Add trace log level
* Add more efficient log leveling
* Retry automatically on ConnPool.Begin (Joseph Glanville)
* Encode from net.IP to inet and cidr
* Generalize encoding pointer to string to any PostgreSQL type
* Add UUID encoding from pointer to string (Joseph Glanville)
* Add null mapping to pointer to pointer (Jonathan Rudenberg)
* Add JSON and JSONB type support (Joseph Glanville)
# 2.6.0 (September 3, 2015)
* Add inet and cidr type support
* Add binary decoding to TimestampOid in stdlib driver (Samuel Stauffer)
* Add support for specifying sslmode in connection strings (Rick Snyder)
* Allow ConnPool to have MaxConnections of 1
* Add basic PGSSLMODE to support to ParseEnvLibpq
* Add fallback TLS config
* Expose specific error for TSL refused
* More error details exposed in PgError
* Support custom dialer (Lewis Marshall)
# 2.5.0 (April 15, 2015)
* Fix stdlib nil support (Blaž Hrastnik)
* Support custom Scanner not reading entire value
* Fix empty array scanning (Laurent Debacker)
* Add ParseDSN (deoxxa)
* Add timestamp support to NullTime
* Remove unused text format scanners
* Return error when too many parameters on Prepare
* Add Travis CI integration (Jonathan Rudenberg)
* Large object support (Jonathan Rudenberg)
* Fix reading null byte arrays (Karl Seguin)
* Add timestamptz[] support
* Add timestamp[] support (Karl Seguin)
* Add bool[] support (Karl Seguin)
* Allow writing []byte into text and varchar columns without type conversion (Hari Bhaskaran)
* Fix ConnPool Close panic
* Add Listen / notify example
* Reduce memory allocations (Karl Seguin)
# 2.4.0 (October 3, 2014)
* Add per connection oid to name map
* Add Hstore support (Andy Walker)
* Move introductory docs to godoc from readme
* Fix documentation references to TextEncoder and BinaryEncoder
* Add keep-alive to TCP connections (Andy Walker)
* Add support for EmptyQueryResponse / Allow no-op Exec (Andy Walker)
* Allow reading any type into []byte
* WaitForNotification detects lost connections quicker
# 2.3.0 (September 16, 2014)
* Truncate logged strings and byte slices
* Extract more error information from PostgreSQL
* Fix data race with Rows and ConnPool
# 4.0.0 (Prerelease)
v4 is a major release with many significant changes.
* Simplified establishing a connection with a connection string.
* All potentially blocking operations now require a context.Context. The non-context aware functions have been removed.
* OIDs are hard-coded for known types. This saves the query on connection.
* Context cancellations while network activity is in progress is now always fatal. Previously, it was sometimes recoverable. This led to increased complexity in pgx itself and in application code.
* Go modules are required.
* Errors are now implemented in the Go 1.13 style. Tests for specific error types must use `As` or `Is`.
* `Rows` is now an interface.
* The connection pool as been decoupled from pgx and is now a separate, included package (github.com/jackc/pgx/v4/pgxpool).
* pgtype has been spun off to a separate package (github.com/jackc/pgtype).
* pgproto3 has been spun off to a separate package (github.com/jackc/pgproto3).
* Lower level PostgreSQL functionality is now implemented in a separate package (github.com/jackc/pgconn).
* Replication support has been temporarily removed. It will be implemented in a separate package.
* Tests are now configured with environment variables.

53
README.md
View File

@ -3,18 +3,29 @@
# pgx - PostgreSQL Driver and Toolkit
pgx is a pure Go driver and toolkit for PostgreSQL. pgx is different from other drivers such as [pq](http://godoc.org/github.com/lib/pq) because, while it can operate as a database/sql compatible driver, pgx is also usable directly. It offers a native interface similar to database/sql that offers better performance and more features.
pgx is a pure Go driver and toolkit for PostgreSQL. It is usable through database/sql but also offers a native interface similar to database/sql that offers better performance and more features.
## Example Usage
```go
conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
fmt.Fprintf(os.Stderr, "Unable to connection to database: %v\n", err)
os.Exit(1)
}
var name string
var weight int64
err := conn.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
err := conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
return err
}
```
## Prerelease v4
This is the `v4` branch. `v4` is still under development but is ready for testing. See [v4 milestone](https://github.com/jackc/pgx/milestone/2) for currently known outstanding issues.
## Features
pgx supports many additional features beyond what is available through database/sql.
@ -35,20 +46,21 @@ pgx supports many additional features beyond what is available through database/
* Large object support
* NULL mapping to Null* struct or pointer to pointer.
* Supports database/sql.Scanner and database/sql/driver.Valuer interfaces for custom types
* Logical replication connections, including receiving WAL and sending standby status updates
* Notice response handling (this is different than listen / notify)
## Performance
## Related Libraries
pgx performs roughly equivalent to [go-pg](https://github.com/go-pg/pg) and is almost always faster than [pq](http://godoc.org/github.com/lib/pq). When parsing large result sets the percentage difference can be significant (16483 queries/sec for pgx vs. 10106 queries/sec for pq -- 63% faster).
pgx is part of a family of PostgreSQL libraries. Many of these can be used independently. Many can also be accessed from pgx for lower-level control.
In many use cases a significant cause of latency is network round trips between the application and the server. pgx supports query batching to bundle multiple queries into a single round trip. Even in the case of a connection with the lowest possible latency, a local Unix domain socket, batching as few as three queries together can yield an improvement of 57%. With a typical network connection the results can be even more substantial.
## github.com/jackc/pgconn
See this [gist](https://gist.github.com/jackc/4996e8648a0c59839bff644f49d6e434) for the underlying benchmark results or checkout [go_db_bench](https://github.com/jackc/go_db_bench) to run tests for yourself.
pgconn is a lower-level PostgreSQL database driver that operates at nearly the same level is the C library libpq.
In addition to the native driver, pgx also includes a number of packages that provide additional functionality.
## github.com/jackc/pgx/v4/pgxpool
## github.com/jackc/pgx/stdlib
pgxpool is a connection pool for pgx. pgx is entirely decoupled from its default pool implementation. This means pgx can be used with a different pool without any pool at all.
## github.com/jackc/pgx/v4/stdlib
database/sql compatibility layer for pgx. pgx can be used as a normal database/sql driver, but at any time the native interface may be acquired for more performance or PostgreSQL specific functionality.
@ -60,10 +72,29 @@ Approximately 60 PostgreSQL types are supported including uuid, hstore, json, by
pgproto3 provides standalone encoding and decoding of the PostgreSQL v3 wire protocol. This is useful for implementing very low level PostgreSQL tooling.
## github.com/jackc/pgx/pgmock
## github.com/jackc/pgx/v4/pgmock
pgmock offers the ability to create a server that mocks the PostgreSQL wire protocol. This is used internally to test pgx by purposely inducing unusual errors. pgproto3 and pgmock together provide most of the foundational tooling required to implement a PostgreSQL proxy or MitM (such as for a custom connection pooler).
## github.com/jackc/tern
tern is a stand-alone SQL migration system.
## Alternatives
* [pq](http://godoc.org/github.com/lib/pq)
* [go-pg](https://github.com/go-pg/pg)
For normal queries with small result sets all drivers perform similarly, but pgx can have a significant advantage with large result sets or when lower level features are used. But for most application use cases the performance difference will be irrelevant. See [go_db_bench](https://github.com/jackc/go_db_bench) to run tests for yourself.
The primary difference between the drivers is features and API style.
pq is exclusively used with database/sql. go-pg does not use database/sql at all. pgx supports database/sql as well as a faster and more featureful native interface.
go-pg has an ORM and schema migration support baked in. pq and pgx do not.
When possible, pgx decouples functionality into separate packages to make it easy to reuse outside of pgx and replace functionality inside. For example, the [pgtype](https://github.com/jackc/pgtype) package that provides support for PostgreSQL types is usable with pq and database/sql and the bundled connection pool is entirely replaceable.
## Documentation
pgx includes extensive documentation in the godoc format. It is viewable online at [godoc.org](https://godoc.org/github.com/jackc/pgx).
@ -97,4 +128,4 @@ PGX_TEST_DATABASE="host=/var/run/postgresql database=pgx_test" go test ./...
## Version Policy
pgx follows semantic versioning for the documented public API on stable releases. Branch `v3` is the latest stable release. `master` can contain new features or behavior that will change or be removed before being merged to the stable `v3` branch (in practice, this occurs very rarely). `v2` is the previous stable release.
pgx follows semantic versioning for the documented public API on stable releases. This is the prerelease of `v4`. Branch `v3` is the latest stable release. `master` can contain new features or behavior that will change or be removed before being merged to the stable `v3` branch (in practice, this occurs very rarely).

59
doc.go
View File

@ -3,7 +3,7 @@
pgx provides lower level access to PostgreSQL than the standard database/sql.
It remains as similar to the database/sql interface as possible while
providing better speed and access to PostgreSQL specific features. Import
github.com/jackc/pgx/stdlib to use pgx as a database/sql compatible driver.
github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.
Query Interface
@ -13,7 +13,7 @@ pgx implements Query and Scan in the familiar database/sql style.
// Send the query to the server. The returned rows MUST be closed
// before conn can be used again.
rows, err := conn.Query("select generate_series(1,$1)", 10)
rows, err := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
if err != nil {
return err
}
@ -45,14 +45,14 @@ pgx also implements QueryRow in the same style as database/sql.
var name string
var weight int64
err := conn.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
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("delete from widgets where id=$1", 42)
commandTag, err := conn.Exec(context.Background(), "delete from widgets where id=$1", 42)
if err != nil {
return err
}
@ -62,22 +62,7 @@ Use Exec to execute a query that does not return a result set.
Connection Pool
Connection pool usage is explicit and configurable. In pgx, a connection can be
created and managed directly, or a connection pool with a configurable maximum
connections can be used. The connection pool offers an after connect hook that
allows every connection to be automatically setup before being made available in
the connection pool.
It delegates methods such as QueryRow to an automatically checked out and
released connection so you can avoid manually acquiring and releasing
connections when you do not need that level of control.
var name string
var weight int64
err := pool.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
return err
}
See sub-package pgxpool for connection pool.
Base Type Mapping
@ -173,16 +158,16 @@ to PostgreSQL.
Transactions
Transactions are started by calling Begin or BeginEx. The BeginEx variant
Transactions are started by calling Begin. The second argument
can create a transaction with a specified isolation level.
tx, err := conn.Begin()
tx, err := conn.Begin(context.Background(), nil)
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()
defer tx.Rollback(context.Background())
_, err = tx.Exec(context.Background(), "insert into foo(id) values (1)")
if err != nil {
@ -207,6 +192,7 @@ implement CopyFromSource to avoid buffering the entire data set in memory.
}
copyCount, err := conn.CopyFrom(
context.Background(),
pgx.Identifier{"people"},
[]string{"first_name", "last_name", "age"},
pgx.CopyFromRows(rows),
@ -216,32 +202,7 @@ 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
WaitForNotification function. It takes a maximum time to wait for a
notification.
err := conn.Exec("listen channelname")
if err != nil {
return nil
}
if notification, err := conn.WaitForNotification(time.Second); err != nil {
// do something with notification
}
TLS
The pgx ConnConfig struct has a TLSConfig field. If this field is
nil, then TLS will be disabled. If it is present, then it will be used to
configure the TLS connection. This allows total configuration of the TLS
connection.
pgx has never explicitly supported Postgres < 9.6's `ssl_renegotiation` option.
As of v3.3.0, it doesn't send `ssl_renegotiation: 0` either to support Redshift
(https://github.com/jackc/pgx/pull/476). If you need TLS Renegotiation,
consider supplying `ConnConfig.TLSConfig` with a non-zero `Renegotiation`
value and if it's not the default on your server, set `ssl_renegotiation`
via `ConnConfig.RuntimeParams`.
Use the underlying pgconn.PgConn for listen and notify.
Logging

81
v4.md
View File

@ -1,81 +0,0 @@
# V4
## Goals
The goal for V4 is to decouple the components of pgx, Conn and ConnPool in particular, such that specialized use cases can compose a custom driver from the driver parts rather than the Conn type have to monolithically support them.
Example cases:
* Almost PostgreSQL servers such as Amazon RedShift, CrateDB, and PgBouncer sometimes need slightly different behavior.
* Connection loss detection and query retry logic is highly application specific.
* Desired connection pool behavior can vary widely (this often goes along with the previous item).
* Replication support may be simpler if decoupled from the current high level pgx.Conn instead of simply wrapping it.
* Alternative or very low level row parsing that bypasses the `Rows.Scan` interface entirely.
Potential Changes:
* Decouple establish connection logic from using a connection. Base connection establishment should be re-usable for multiple connection types.
* Decouple connection pool from connections. Connection pool should be entirely replaceable.
* Decouple various logical layers of PostgreSQL connection such that an advanced user can choose what layer to work at and pgx still handles the lower level details. e.g Normal high level query level, PostgreSQL wire protocol message level, or wire byte level.
* Change prepared statement usage from using name as SQL text to specifically calling prepared statement (more like database/sql).
* Remove stdlib hack for RegisterDriverConfig now that database/sql supports better way
* Consider how to simplify context.Context and query cancellation support (or even remove). This logic is very complex and error prone. Perhaps connections should simply be killed on a cancelled context rather than trying to recover. Separating PostgreSQL query cancellation from context might simplify them both. Also consider that PG queries can be cancelled and connections can be terminated via SQL functions from another connection.
* Better error handling. Consider package functions that interrogate errors rather comparing to value or type. Like net.Error interface but with addition of package functions that unwrap and interrogate the error. Maybe target the Go 2 error proposal.
* Add function that extracts logger from context to conn config.
* get logger from context or maybe logger receives context
* Maybe move to zerolog style interface for logging
* Add libpq style function layer: sendquery, sendpreparedquery, getresults etc.
* Consider strongly typed row scan in style of zerolog (chained functions instead of varargs)
* Consider strongly typed query parameters in style of zerolog (chained functions instead of varargs)
* Consider buffered query select where entire result set is received and parsed successfully or call returns error
## Changes
* `pgconn.PgConn` now contains core PostgreSQL connection functionality.
* Test configuration now done with environment variables instead of `.gitignore`'d locally modified `conn_config_test.go` file.
* PostgreSQL errors are now `*pgconn.PgError` instead of `pgx.PgError`.
### Incompatible Changes
* Connect method now takes context and connection string.
* ConnectConfig takes context and config object.
* `RuntimeParams` `pgx.Conn`. Server reported status can now be queried with the `ParameterStatus` method. The rename aligns with the PostgreSQL protocol and standard libpq naming. Access via a method instead of direct access to the map protects against outside modification.
* LISTEN / NOTIFY functionality moved to pgconn.
* COPY TO functionality moved to pgconn.
* COPY FROM functionality moved to pgconn.
## New Features
* Specifying multiple hosts for connecting to HA systems.
## Transaction idea
Problem: Using original connection or pool outside of tx object
tx = pool.Begin()
tx.Query(...)
pool.Query(...) // <- Possible to accidentally do stuff outside of tx
Solution: Common interface for basic queries and atomicity
var querier Querier
querier = pool
querier = querier.Begin() <- tx implements querier
querier.Query(...)
querier = querier.Commit()
-- tx implements begin, commit, and rollback as save points
-- conn implements begin as create tx (what about commit and rollback? No-op?)
-- pool implements begin as?
## Errors
Consider Go error values proposal
https://go.googlesource.com/proposal/+/master/design/go2draft-error-values-overview.md
https://godoc.org/golang.org/x/xerrors