back to listing index

jackc/pgx

[web search]
Original source (github.com)
Tags: postgres postgresql golang go pgx
Clipped on: 2016-04-27

Skip to content
PostgreSQL client library for Go
Go
Latest commit 623ba1e 4 hours ago Image (Asset 2/2) alt= Add scan to uint16
examples Add example of listen/notify support 2 years ago
stdlib Fix skip JSON tests for old servers 6 months ago
.gitignore Rename ConnectionParameters to ConnConfig 2 years ago
.travis.yml Update travis build matrix a month ago
CHANGELOG.md Release 2.8.1 a month ago
LICENSE Add license 3 years ago
README.md Support decoding inet/cidr to net.IP 5 days ago
bench_test.go Add basic benchmark for ConnPoolQueryRow 2 months ago
conn.go Fix some golint errors 29 days ago
conn_config_test.go.example Support using a custom dialer a year ago
conn_config_test.go.travis Support using a custom dialer a year ago
conn_pool.go Add AcquireTimeout support 16 days ago
conn_pool_test.go Add AcquireTimeout support 16 days ago
conn_test.go TestFatalRxError expects multiple error types a month ago
doc.go Add compatibility with database/sql custom types 4 months ago
example_custom_type_test.go Enhance support for custom types 2 years ago
example_json_test.go Fake example if PostgreSQL server too old for JSON 8 months ago
fastpath.go Use binary transcoding for inet/cidr 8 months ago
helper_test.go Fix go vet identified format strings 2 months ago
hstore.go Fix go vet identified format strings 2 months ago
hstore_test.go Fix go vet identified composite leteral uses unkeyed fields 2 months ago
large_objects.go Minor docs fixes for large objects a year ago
large_objects_test.go Implement large object support a year ago
logger.go Fix some golint errors 29 days ago
messages.go Use binary transcoding for inet/cidr 8 months ago
msg_reader.go Add *Conn.SetLogLevel 2 months ago
query.go Fix some golint errors 29 days ago
query_test.go Add scan to uint16 4 hours ago
sql.go Add QueryArgs 2 years ago
sql_test.go Update github.com/JackC to github.com/jackc 2 years ago
stress_test.go Add ConnPool Prepare and Deallocate 2 months ago
tx.go Fix some golint errors 29 days ago
tx_test.go Fix Tx.status not being set on error on Commit a month ago
value_reader.go Fix some golint errors 29 days ago
values.go Add scan to uint16 4 hours ago
values_test.go Support decoding inet/cidr to net.IP 5 days ago

README.md

Pgx

Pgx is a a pure Go database connection library designed specifically for PostgreSQL. Pgx is different from other drivers such as 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.

Features

Pgx supports many additional features beyond what is available through database/sql.

  • Listen / notify
  • Transaction isolation level control
  • Full TLS connection control
  • Binary format support for custom types (can be much faster)
  • Logging support
  • Configurable connection pool with after connect hooks to do arbitrary connection setup
  • PostgreSQL array to Go slice mapping for integers, floats, and strings
  • Hstore support
  • JSON and JSONB support
  • Maps inet and cidr PostgreSQL types to net.IPNet and net.IP
  • 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

Performance

Pgx performs roughly equivalent to pq and go-pg for selecting a single column from a single row, but it is substantially faster when selecting multiple entire rows (6893 queries/sec for pgx vs. 3968 queries/sec for pq -- 73% faster).

See this gist for the underlying benchmark results or checkout go_db_bench to run tests for yourself.

database/sql

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.

Documentation

pgx includes extensive documentation in the godoc format. It is viewable online at godoc.org.

Testing

pgx supports multiple connection and authentication types. Setting up a test environment that can test all of them can be cumbersome. In particular, Windows cannot test Unix domain socket connections. Because of this pgx will skip tests for connection types that are not configured.

Normal Test Environment

To setup the normal test environment run the following SQL:

normalcreate user pgx_md5 password 'secret';
create database pgx_test;
normal

Connect to database pgx_test and run:

normalcreate extension hstore;
normal

Next open connection_settings_test.go.example and make a copy without the .example. If your PostgreSQL server is accepting connections on 127.0.0.1, then you are done.

Connection and Authentication Test Environment

Complete the normal test environment setup and also do the following.

Run the following SQL:

normalcreate user pgx_none;
create user pgx_pw password 'secret';
normal

Add the following to your pg_hba.conf:

If you are developing on Unix with domain socket connections:

normallocal  pgx_test  pgx_none  trust
local  pgx_test  pgx_pw    password
local  pgx_test  pgx_md5   md5
normal

If you are developing on Windows with TCP connections:

normalhost  pgx_test  pgx_none  127.0.0.1/32 trust
host  pgx_test  pgx_pw    127.0.0.1/32 password
host  pgx_test  pgx_md5   127.0.0.1/32 md5
normal

Version Policy

pgx follows semantic versioning for the documented public API.  master  branch tracks the latest stable branch ( v2 ). Consider using  import "gopkg.in/jackc/pgx.v2"  to lock to the  v2  branch or use a vendoring tool such as godep.