• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

chunkreader/H05-Feb-2018-

examples/H05-Feb-2018-

internal/sanitize/H05-Feb-2018-

log/H05-Feb-2018-

pgio/H05-Feb-2018-

pgmock/H05-Feb-2018-

pgproto3/H05-Feb-2018-

pgtype/H05-Feb-2018-

stdlib/H05-Feb-2018-

travis/H05-Feb-2018-

.gitignoreH A D05-Feb-2018280

.travis.ymlH A D05-Feb-2018525

CHANGELOG.mdH A D05-Feb-201811 KiB

LICENSEH A D05-Feb-20181 KiB

README.mdH A D05-Feb-20186.6 KiB

batch.goH A D05-Feb-20187.2 KiB

batch_test.goH A D05-Feb-201813.2 KiB

bench-tmp_test.goH A D05-Feb-20181 KiB

bench_test.goH A D05-Feb-201815.1 KiB

conn.goH A D05-Feb-201849 KiB

conn_config_test.go.exampleH A D05-Feb-20183.1 KiB

conn_config_test.go.travisH A D05-Feb-20181.7 KiB

conn_pool.goH A D05-Feb-201815.9 KiB

conn_pool_private_test.goH A D05-Feb-20181 KiB

conn_pool_test.goH A D05-Feb-201824.9 KiB

conn_test.goH A D05-Feb-201850 KiB

copy_from.goH A D05-Feb-20185.5 KiB

copy_from_test.goH A D05-Feb-20189.9 KiB

doc.goH A D05-Feb-20187.1 KiB

example_custom_type_test.goH A D05-Feb-20182 KiB

example_json_test.goH A D05-Feb-2018541

fastpath.goH A D05-Feb-20182.6 KiB

go_stdlib.goH A D05-Feb-20182.5 KiB

helper_test.goH A D05-Feb-20181.6 KiB

large_objects.goH A D05-Feb-20184.2 KiB

large_objects_test.goH A D05-Feb-20182 KiB

logger.goH A D05-Feb-20181.9 KiB

messages.goH A D05-Feb-20185.4 KiB

pgpass.goH A D05-Feb-20181.4 KiB

pgpass_test.goH A D05-Feb-20181.2 KiB

private_test.goH A D05-Feb-2018139

query.goH A D05-Feb-201813.9 KiB

query_test.goH A D05-Feb-201840.4 KiB

replication.goH A D05-Feb-201814 KiB

replication_test.goH A D05-Feb-20189.4 KiB

sql.goH A D05-Feb-2018651

sql_test.goH A D05-Feb-2018721

stress_test.goH A D05-Feb-20187.9 KiB

tx.goH A D05-Feb-20186.8 KiB

tx_test.goH A D05-Feb-20188.8 KiB

values.goH A D05-Feb-20186.1 KiB

values_test.goH A D05-Feb-201825.1 KiB

README.md

1[![](https://godoc.org/github.com/jackc/pgx?status.svg)](https://godoc.org/github.com/jackc/pgx)
2[![Build Status](https://travis-ci.org/jackc/pgx.svg)](https://travis-ci.org/jackc/pgx)
3
4# pgx - PostgreSQL Driver and Toolkit
5
6pgx 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.
7
8
9```go
10var name string
11var weight int64
12err := conn.QueryRow("select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
13if err != nil {
14    return err
15}
16```
17
18## Features
19
20pgx supports many additional features beyond what is available through database/sql.
21
22* Support for approximately 60 different PostgreSQL types
23* Batch queries
24* Single-round trip query mode
25* Full TLS connection control
26* Binary format support for custom types (can be much faster)
27* Copy protocol support for faster bulk data loads
28* Extendable logging support including built-in support for log15 and logrus
29* Connection pool with after connect hook to do arbitrary connection setup
30* Listen / notify
31* PostgreSQL array to Go slice mapping for integers, floats, and strings
32* Hstore support
33* JSON and JSONB support
34* Maps inet and cidr PostgreSQL types to net.IPNet and net.IP
35* Large object support
36* NULL mapping to Null* struct or pointer to pointer.
37* Supports database/sql.Scanner and database/sql/driver.Valuer interfaces for custom types
38* Logical replication connections, including receiving WAL and sending standby status updates
39* Notice response handling (this is different than listen / notify)
40
41## Performance
42
43pgx 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).
44
45In 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.
46
47See 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.
48
49In addition to the native driver, pgx also includes a number of packages that provide additional functionality.
50
51## github.com/jackc/pgx/stdlib
52
53database/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.
54
55## github.com/jackc/pgx/pgtype
56
57Approximately 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.
58
59## github.com/jackc/pgx/pgproto3
60
61pgproto3 provides standalone encoding and decoding of the PostgreSQL v3 wire protocol. This is useful for implementing very low level PostgreSQL tooling.
62
63## github.com/jackc/pgx/pgmock
64
65pgmock 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).
66
67## Documentation
68
69pgx includes extensive documentation in the godoc format. It is viewable online at [godoc.org](https://godoc.org/github.com/jackc/pgx).
70
71## Testing
72
73pgx supports multiple connection and authentication types. Setting up a test
74environment that can test all of them can be cumbersome. In particular,
75Windows cannot test Unix domain socket connections. Because of this pgx will
76skip tests for connection types that are not configured.
77
78### Normal Test Environment
79
80To setup the normal test environment, first install these dependencies:
81
82    go get github.com/cockroachdb/apd
83    go get github.com/hashicorp/go-version
84    go get github.com/jackc/fake
85    go get github.com/lib/pq
86    go get github.com/pkg/errors
87    go get github.com/satori/go.uuid
88    go get github.com/shopspring/decimal
89    go get github.com/sirupsen/logrus
90    go get go.uber.org/zap
91    go get gopkg.in/inconshreveable/log15.v2
92
93Then run the following SQL:
94
95    create user pgx_md5 password 'secret';
96    create user " tricky, ' } "" \ test user " password 'secret';
97    create database pgx_test;
98    create user pgx_replication with replication password 'secret';
99
100Connect to database pgx_test and run:
101
102    create extension hstore;
103
104Next open conn_config_test.go.example and make a copy without the
105.example. If your PostgreSQL server is accepting connections on 127.0.0.1,
106then you are done.
107
108### Connection and Authentication Test Environment
109
110Complete the normal test environment setup and also do the following.
111
112Run the following SQL:
113
114    create user pgx_none;
115    create user pgx_pw password 'secret';
116
117Add the following to your pg_hba.conf:
118
119If you are developing on Unix with domain socket connections:
120
121    local  pgx_test  pgx_none  trust
122    local  pgx_test  pgx_pw    password
123    local  pgx_test  pgx_md5   md5
124
125If you are developing on Windows with TCP connections:
126
127    host  pgx_test  pgx_none  127.0.0.1/32 trust
128    host  pgx_test  pgx_pw    127.0.0.1/32 password
129    host  pgx_test  pgx_md5   127.0.0.1/32 md5
130
131### Replication Test Environment
132
133Add a replication user:
134
135    create user pgx_replication with replication password 'secret';
136
137Add a replication line to your pg_hba.conf:
138
139    host replication pgx_replication 127.0.0.1/32 md5
140
141Change the following settings in your postgresql.conf:
142
143    wal_level=logical
144    max_wal_senders=5
145    max_replication_slots=5
146
147Set `replicationConnConfig` appropriately in `conn_config_test.go`.
148
149## Version Policy
150
151pgx 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.
152