pgx/v4.md

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.
• 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

Minor Potential Changes:

• Change PgError error implementation to pointer method

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.

New Features

• Specifying multiple hosts for connecting to HA systems.