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

Various doc and changelog tweaks

v5-dev
Jack Christensen 2022-09-17 09:03:48 -05:00
parent a05fb80b8a
commit 4f1a8084f1
3 changed files with 29 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
CHANGELOG.md
View File

@ -1,4 +1,4 @@
# Unreleased v5 # v5.0.0
## Merged Packages ## Merged Packages
@ -33,7 +33,7 @@ The `pgtype` package has been significantly changed.
### NULL Representation ### NULL Representation
Previously, types had a `Status` field that could be `Undefined`, `Null`, or `Present`. This has been changed to a Previously, types had a `Status` field that could be `Undefined`, `Null`, or `Present`. This has been changed to a
`Valid` `bool` field to harmonize with how `database/sql` represents NULL and to make the zero value useable. `Valid` `bool` field to harmonize with how `database/sql` represents `NULL` and to make the zero value useable.
### Codec and Value Split ### Codec and Value Split
@ -47,9 +47,9 @@ generally defined by implementing an interface that a particular `Codec` underst
### Array Types ### Array Types
All array types are now handled by `ArrayCodec` instead of using code generation for each new array type. This All array types are now handled by `ArrayCodec` instead of using code generation for each new array type. This also
significantly reduced the amount of code and the compiled binary size. This also means that less common array types such means that less common array types such as `point[]` are now supported. `Array[T]` supports PostgreSQL multi-dimensional
as `point[]` are now supported. `Array[T]` supports PostgreSQL multi-dimensional arrays. arrays.
### Composite Types ### Composite Types
@ -63,7 +63,7 @@ easily be handled. Multirange types are handled similarly with `MultirangeCodec`
### pgxtype ### pgxtype
load data type moved to conn `LoadDataType` moved to `*Conn` as `LoadType`.
### Bytea ### Bytea
@ -97,7 +97,7 @@ This matches the convention set by `database/sql`. In addition, for comparable t
### 3rd Party Type Integrations ### 3rd Party Type Integrations
* Extracted integrations with github.com/shopspring/decimal and github.com/gofrs/uuid to * Extracted integrations with https://github.com/shopspring/decimal and https://github.com/gofrs/uuid to
https://github.com/jackc/pgx-shopspring-decimal and https://github.com/jackc/pgx-gofrs-uuid respectively. This trims https://github.com/jackc/pgx-shopspring-decimal and https://github.com/jackc/pgx-gofrs-uuid respectively. This trims
the pgx dependency tree. the pgx dependency tree.

58
README.md
View File

@ -1,15 +1,12 @@
[![](https://godoc.org/github.com/jackc/pgx?status.svg)](https://pkg.go.dev/github.com/jackc/pgx/v5) [![](https://godoc.org/github.com/jackc/pgx?status.svg)](https://pkg.go.dev/github.com/jackc/pgx/v5)
[![Build Status](https://travis-ci.org/jackc/pgx.svg)](https://travis-ci.org/jackc/pgx) ![Build Status](https://github.com/jackc/pgx/actions/workflows/ci.yml/badge.svg)
# pgx - PostgreSQL Driver and Toolkit # pgx - PostgreSQL Driver and Toolkit
*This is the v5 development branch. It is still in beta testing.*
pgx is a pure Go driver and toolkit for PostgreSQL. pgx is a pure Go driver and toolkit for PostgreSQL.
pgx aims to be low-level, fast, and performant, while also enabling PostgreSQL-specific features that the standard `database/sql` package does not allow for. The pgx driver is a low-level, high performance interface that exposes PostgreSQL-specific features such as `LISTEN` /
`NOTIFY` and `COPY`. It also includes an adapter for the standard `database/sql` interface.
The driver component of pgx can be used alongside the standard `database/sql` package.
The toolkit component is a related set of packages that implement PostgreSQL functionality such as parsing the wire protocol The toolkit component is a related set of packages that implement PostgreSQL functionality such as parsing the wire protocol
and type mapping between PostgreSQL and Go. These underlying packages can be used to implement alternative drivers, and type mapping between PostgreSQL and Go. These underlying packages can be used to implement alternative drivers,
@ -51,52 +48,39 @@ func main() {
See the [getting started guide](https://github.com/jackc/pgx/wiki/Getting-started-with-pgx) for more information. See the [getting started guide](https://github.com/jackc/pgx/wiki/Getting-started-with-pgx) for more information.
## Choosing Between the pgx and database/sql Interfaces
It is recommended to use the pgx interface if:
1. The application only targets PostgreSQL.
2. No other libraries that require `database/sql` are in use.
The pgx interface is faster and exposes more features.
The `database/sql` interface only allows the underlying driver to return or receive the following types: `int64`,
`float64`, `bool`, `[]byte`, `string`, `time.Time`, or `nil`. Handling other types requires implementing the
`database/sql.Scanner` and the `database/sql/driver/driver.Valuer` interfaces which require transmission of values in text format. The binary format can be substantially faster, which is what the pgx interface uses.
## Features ## Features
pgx supports many features beyond what is available through `database/sql`:
* Support for approximately 70 different PostgreSQL types * Support for approximately 70 different PostgreSQL types
* Automatic statement preparation and caching * Automatic statement preparation and caching
* Batch queries * Batch queries
* Single-round trip query mode * Single-round trip query mode
* Full TLS connection control * Full TLS connection control
* Binary format support for custom types (allows for much quicker encoding/decoding) * Binary format support for custom types (allows for much quicker encoding/decoding)
* COPY protocol support for faster bulk data loads * `COPY` protocol support for faster bulk data loads
* Extendable logging support * Tracing and logging support
* Connection pool with after-connect hook for arbitrary connection setup * Connection pool with after-connect hook for arbitrary connection setup
* Listen / notify * `LISTEN` / `NOTIFY`
* Conversion of PostgreSQL arrays to Go slice mappings for integers, floats, and strings * Conversion of PostgreSQL arrays to Go slice mappings for integers, floats, and strings
* Hstore support * `hstore` support
* JSON and JSONB support * `json` and `jsonb` support
* Maps `inet` and `cidr` PostgreSQL types to `netip.Addr` and `netip.Prefix` * Maps `inet` and `cidr` PostgreSQL types to `netip.Addr` and `netip.Prefix`
* Large object support * Large object support
* NULL mapping to Null* struct or pointer to pointer * NULL mapping to pointer to pointer
* Supports `database/sql.Scanner` and `database/sql/driver.Valuer` interfaces for custom types * Supports `database/sql.Scanner` and `database/sql/driver.Valuer` interfaces for custom types
* Notice response handling * Notice response handling
* Simulated nested transactions with savepoints * Simulated nested transactions with savepoints
## Performance ## Choosing Between the pgx and database/sql Interfaces
There are three areas in particular where pgx can provide a significant performance advantage over the standard The pgx interface is faster. Many PostgreSQL specific features such as `LISTEN` / `NOTIFY` and `COPY` are not available
`database/sql` interface and other drivers: through the `database/sql` interface.
1. PostgreSQL specific types - Types such as arrays can be parsed much quicker because pgx uses the binary format. The pgx interface is recommended when:
2. Automatic statement preparation and caching - pgx will prepare and cache statements by default. This can provide an
significant free improvement to code that does not explicitly use prepared statements. Under certain workloads, it can 1. The application only targets PostgreSQL.
perform nearly 3x the number of queries per second. 2. No other libraries that require `database/sql` are in use.
3. Batched queries - Multiple queries can be batched together to minimize network round trips.
It is also possible to use the `database/sql` interface and convert a connection to the lower-level pgx interface as needed.
## Testing ## Testing
@ -129,13 +113,11 @@ In addition, there are tests specific for PgBouncer that will be executed if `PG
## Supported Go and PostgreSQL Versions ## Supported Go and PostgreSQL Versions
~~pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases and for [PostgreSQL](https://www.postgresql.org/support/versioning/) the major releases in the last 5 years. This means pgx supports Go 1.17 and higher and PostgreSQL 10 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/).~~ pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases and for [PostgreSQL](https://www.postgresql.org/support/versioning/) the major releases in the last 5 years. This means pgx supports Go 1.18 and higher and PostgreSQL 10 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/).
`v5` is targeted at Go 1.18+. The general release of `v5` is not planned until second half of 2022 so it is expected that the policy of supporting the two most recent versions of Go will be maintained or restored soon after its release.
## Version Policy ## Version Policy
pgx follows semantic versioning for the documented public API on stable releases. `v4` is the latest stable major version. pgx follows semantic versioning for the documented public API on stable releases. `v5` is the latest stable major version.
## PGX Family Libraries ## PGX Family Libraries

3
doc.go
View File

@ -97,7 +97,8 @@ Transactions are started by calling Begin.
The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions. The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions.
These are internally implemented with savepoints. These are internally implemented with savepoints.
Use BeginTx to control the transaction mode. Use BeginTx to control the transaction mode. BeginTx also can be used to ensure a new transaction is created instead of
a pseudo nested transaction.
BeginFunc and BeginTxFunc are functions that begin a transaction, execute a function, and commit or rollback the BeginFunc and BeginTxFunc are functions that begin a transaction, execute a function, and commit or rollback the
transaction depending on the return value of the function. These can be simpler and less error prone to use. transaction depending on the return value of the function. These can be simpler and less error prone to use.