pq

README

pq - A pure Go postgres driver for Go's database/sql package

Install

go get github.com/lib/pq

Docs

http://godoc.org/github.com/lib/pq

Use

package main

import (
	_ "github.com/lib/pq"
	"database/sql"
)

func main() {
	db, err := sql.Open("postgres", "user=pqgotest dbname=pqgotest sslmode=verify-full")
	// ...
}

Connection String Parameters

These are a subset of the libpq connection parameters. In addition, a number of the environment variables supported by libpq are also supported. Just like libpq, these have lower precedence than explicitly provided connection parameters.

See http://www.postgresql.org/docs/9.1/static/libpq-connect.html.

• dbname - The name of the database to connect to
• user - The user to sign in as
• password - The user's password
• host - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost)
• port - The port to bind to. (default is 5432)
• sslmode - Whether or not to use SSL (default is require, this is not the default for libpq) Valid values are:
  • disable - No SSL
  • require - Always SSL (skip verification)
  • verify-full - Always SSL (require verification)

See http://golang.org/pkg/database/sql to learn how to use with pq through the database/sql package.

Listening for notifications

PostgreSQL supports a simple publish/subscribe model over the database connections. See http://www.postgresql.org/docs/9.1/static/sql-notify.html for more information.

pq supports this using an infinite Rows object. When issuing a Query("LISTEN <channel>"), the query is sent to the server, and a special Rows object is returned. It always has the columns

• bePid int - The backend process ID
• relname string - The channel name
• payload string - The payload given to NOTIFY, or empty.

When the statement object is closed, an implicit UNLISTEN is sent to the server.

The Next() method of the returned Rows will never reach EOF, except if the connection is terminated. Note that while Next() is being called, there is no way of interrupting the call.

Tests

go test is used for testing. A running PostgreSQL server is required, with the ability to log in. The default database to connect to test with is "pqgotest," but it can be overridden using environment variables.

Example:

PGHOST=/var/run/postgresql go test pq

Features

• SSL
• Handles bad connections for database/sql
• Scan time.Time correctly (i.e. timestamp[tz], time[tz], date)
• Scan binary blobs correctly (i.e. bytea)
• pq.ParseURL for converting urls to connection strings for sql.Open.
• Many libpq compatible environment variables
• Unix socket support
• Notifications: LISTEN/NOTIFY

Future / Things you can help with

• Notifications: Allow listening on multiple channels at once
• hstore sugar (i.e. handling hstore in rows.Scan)

Thank you (alphabetical)

Some of these contributors are from the original library bmizerany/pq.go whose code still exists in here.

• Andy Balholm (andybalholm)
• Ben Berkert (benburkert)
• Bjørn Madsen (aeons)
• Blake Gentry (bgentry)
• Brad Fitzpatrick (bradfitz)
• Daniel Farina (fdr)
• Everyone at The Go Team
• Ewan Chou (coocood)
• Federico Romero (federomero)
• Gary Burd (garyburd)
• Heroku (heroku)
• Jason McVetta (jmcvetta)
• Joakim Sernbrant (serbaut)
• John Gallagher (jgallagher)
• Kamil Kisiel (kisielk)
• Keith Rarick (kr)
• Maciek Sakrejda (deafbybeheading)
• Marc Brinkmann (mbr)
• Martin Olsen (martinolsen)
• Mike Lewis (mikelikespie)
• Ryan Smith (ryandotsmith)
• Samuel Stauffer (samuel)
• notedit (notedit)

Documentation

Overview

Package pq is a pure Go Postgres driver for the database/sql package.

Package pq is a pure Go Postgres driver for the database/sql package. This module contains support for Postgres LISTEN/NOTIFY.

Index

• Constants
• Variables
• func Open(name string) (_ driver.Conn, err error)
• func ParseURL(url string) (string, error)
• type Error
• type Listener
  • func NewListener(name string) (*Listener, error)
  • func (l *Listener) Close() error
  • func (l *Listener) Listen(relname string, c chan<- *Notification) error
  • func (l *Listener) Unlisten(relname string, c chan<- *Notification) error
• type Notification
• type NullTime
  • func (nt *NullTime) Scan(value interface{}) error
  • func (nt NullTime) Value() (driver.Value, error)
• type PGError
• type SimplePGError
  • func (err *SimplePGError) Error() string
  • func (err *SimplePGError) Fatal() bool
  • func (err *SimplePGError) Get(k byte) (v string)
• type Values
  • func (vs Values) Get(k string) (v string)
  • func (vs Values) Set(k, v string)

Constants

const (
	Efatal   = "FATAL"
	Epanic   = "PANIC"
	Ewarning = "WARNING"
	Enotice  = "NOTICE"
	Edebug   = "DEBUG"
	Einfo    = "INFO"
	Elog     = "LOG"
)

const MaxReconnectDelay time.Duration = 15 * time.Minute

The maximum back-off for reconnection.

const MinReconnectDelay time.Duration = 3 * time.Second

The minimum/initial back-off for reconnection.

const Reconnected int = -1

Special bePid value issued on reconnection.

Variables

var (
	ErrSSLNotSupported = errors.New("pq: SSL is not enabled on the server")
	ErrNotSupported    = errors.New("pq: invalid command")
)

Functions

func Open

func Open(name string) (_ driver.Conn, err error)

func ParseURL

func ParseURL(url string) (string, error)

ParseURL converts url to a connection string for driver.Open. Example:

"postgres://bob:secret@1.2.3.4:5432/mydb?sslmode=verify-full"

converts to:

"user=bob password=secret host=1.2.3.4 port=5432 dbname=mydb sslmode=verify-full"

A minimal example:

"postgres://"

This will be blank, causing driver.Open to use all of the defaults

Types

type Error

type Error error

type Listener

type Listener struct {
	// contains filtered or unexported fields
}

func NewListener

func NewListener(name string) (*Listener, error)

func (*Listener) Close

func (l *Listener) Close() error

func (*Listener) Listen

func (l *Listener) Listen(relname string, c chan<- *Notification) error

func (*Listener) Unlisten

func (l *Listener) Unlisten(relname string, c chan<- *Notification) error

type Notification

type Notification struct {
	BePid   int
	RelName string
	Extra   string
}

type NullTime

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

func (*NullTime) Scan

func (nt *NullTime) Scan(value interface{}) error

Scan implements the Scanner interface.

func (NullTime) Value

func (nt NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type PGError

type PGError interface {
	Error() string
	Fatal() bool
	Get(k byte) (v string)
}

type SimplePGError

type SimplePGError struct {
	// contains filtered or unexported fields
}

func (*SimplePGError) Error

func (err *SimplePGError) Error() string

func (*SimplePGError) Fatal

func (err *SimplePGError) Fatal() bool

func (*SimplePGError) Get

func (err *SimplePGError) Get(k byte) (v string)

type Values

type Values map[string]string

func (Values) Get

func (vs Values) Get(k string) (v string)

func (Values) Set

func (vs Values) Set(k, v string)