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)

Use single quotes for values that contain whitespace:

"user=pqgotest password='with spaces'"

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

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 github.com/lib/pq

Optionally, a benchmark suite can be run as part of the tests:

PGHOST=/var/run/postgresql go test -bench .

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

Future / Things you can help with

• Notifications: LISTEN/NOTIFY
• 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)
• Bill Mill (llimllib)
• Bjørn Madsen (aeons)
• Blake Gentry (bgentry)
• Brad Fitzpatrick (bradfitz)
• Chris Walsh (cwds)
• Daniel Farina (fdr)
• Everyone at The Go Team
• Evan Shaw (edsrzf)
• 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)
• Matt Robenolt (mattrobenolt)
• 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.

Index

• Constants
• Variables
• func NewScanner(s string) *scanner
• func Open(name string) (_ driver.Conn, err error)
• func ParseURL(url string) (string, error)
• type Error
• 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"
)

Variables

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

Functions

func NewScanner

func NewScanner(s string) *scanner

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 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)