pgsql.go is a high-level wrapper for the PostgreSQL database libpq client library.

The pgsql.go package Makefile assumes that the libpq library is installed at /usr/local/pgsql/lib/libpq.so and that the libpq headers are under /usr/local/pgsql/include. Modify the Makefile to suit your setup.

To use the compiled pgsql.go package, the libpq.so library directory should be in your library path (e.g., $LD_LIBRARY_PATH on Linux).

cd $GOROOT/src/pkg
git clone git://github.com/jbarham/pgsql.go.git github.com/jbarham/pgsql.go
cd github.com/jbarham/pgsql.go
make install

The package self-test pgsql_test.go assumes that the user running the test can connect to a running PostgreSQL server on localhost with an existing testdb database. See the PostgreSQL installation documentation (short version) for how to create a test database, or adjust the test connection parameters to suit your setup.

import "github.com/jbarham/pgsql.go"

See the package test file pgsql_test.go for example usage.

Two goroutines cannot safely use the same database connection at the same time. However it's often necessary for multiple goroutines to access a database simultaneously, such as when creating a goroutine per HTTP request in a web server. It's also relatively inefficient to create a new database connection for transient goroutines.

For this type of situation, pgsql.go provides a connection pool type Pool which allows for safe sharing of multiple connections between any number of goroutines in the same process.

To create and use a connection pool, simply do the following (with error handling omitted):

// In main goroutine:
// Create a connection pool with up to 3 connections.
pool, _ := pgsql.NewPool("dbname=testdb", 3, pgsql.DEFAULT_IDLE_TIMEOUT)

// In worker goroutine:
conn, _ := pool.Acquire() // Get a connection from the pool.
// Use the connection normally.
result, _ := conn.Query("SELECT SUM(balance) FROM account")
result.Next()
// ...
pool.Release(conn) // Release the connection back to the pool.

For a complete example demonstrating connection pool usage, see the file pool_example.go.

pgsql.go was written by John E. Barham ([email protected]).

The API is inspired by the gosqlite package by Russ Cox.