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

Update README for v3 release

pull/291/merge
Jack Christensen 2017-07-24 08:04:01 -05:00
parent a147e0f3b8
commit 534ea4a9cb
1 changed files with 24 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
README.md
View File

@ -2,35 +2,21 @@
# pgx - PostgreSQL Driver and Toolkit
## Version 3 Beta Branch
This is the `v3` branch which is currently in beta. General release is planned
for July. `v2` is the current release branch. `v3` is considered to be stable in
the sense of lack of known bugs, but the API is not considered stable until
general release. No further changes are planned, but the beta process may
surface desirable changes. If possible API changes are acceptable, then `v3` is
the recommended branch for new development.
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 primarily intended to be
used 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. 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.
## Features
pgx supports many additional features beyond what is available through database/sql.
* pgtype package includes support for approximately 60 different PostgreSQL types - these are usable in pgx native and any database/sql PostgreSQL adapter
* Support for approximately 60 different PostgreSQL types
* Batch queries
* Single-round trip query mode
* Full TLS connection control
* Binary format support for custom types (can be much faster)
* Copy protocol support for faster bulk data loads
* Extendable logging support including builtin support for log15 and logrus
* Configurable connection pool with after connect hooks to do arbitrary connection setup
* Extendable logging support including built-in support for log15 and logrus
* Connection pool with after connect hook to do arbitrary connection setup
* Listen / notify
* Transaction isolation level control
* PostgreSQL array to Go slice mapping for integers, floats, and strings
* Hstore support
* JSON and JSONB support
@ -40,32 +26,32 @@ pgx supports many additional features beyond what is available through database/
* 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)
* pgproto3 package can encode and decode the PostgreSQL version 3 wire protocol
## Performance
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 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).
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 the fastest possible
connection, 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.
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.
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.
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.
## database/sql
In addition to the native driver, pgx also includes a number of packages that provide additional functionality.
Import the ```github.com/jackc/pgx/stdlib``` package to use pgx as a driver for
database/sql. It is possible to retrieve a pgx connection from database/sql on
demand. This allows using the database/sql interface in most places, but using
pgx directly when more performance or PostgreSQL specific features are needed.
## github.com/jackc/pgxstdlib
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.
## github.com/jackc/pgx/pgtype
Approximately 60 PostgreSQL types are supported including uuid, hstore, json, bytea, numeric, interval, inet, and arrays. These types support database/sql interfaces and are usable even outside of pgx. They are fully tested in pgx and pq. They also support a higher performance interface when used with the pgx driver.
## github.com/jackc/pgx/pgproto3
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
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).
## Documentation
@ -144,4 +130,4 @@ Set `replicationConnConfig` appropriately in `conn_config_test.go`.
## Version Policy
pgx follows semantic versioning for the documented public API on stable releases. Branch `v2` is the latest stable release. `master` can contain new features or behavior that will change or be removed before being merged to the stable `v2` branch (in practice, this occurs very rarely).
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.