README
¶
About go-pgsql ============== go-pgsql is a [PostgreSQL](http://www.postgresql.org) client library for the [Go](http://golang.org) programming language. It partially implements version 3.0 of the [PostgreSQL](http://www.postgresql.org) frontend/backend protocol, so it should work with servers of version 7.4 and later. It now supports database/sql in addition to its existing interface. Installing go-pgsql =================== First make sure you have a working [Go](http://golang.org) installation, see the installation guide at http://golang.org/doc/install.html Now you should be able to install go-pgsql by running `go get github.com/lxn/go-pgsql` Using go-pgsql ============== There are some examples in the [examples](examples) directory which should get you started. Please open an issue on the bug tracker if you encounter a bug. Missing Features ================ go-pgsql is currently missing support for some features, including: - authentication types other than MD5 - SSL encrypted sessions - some data types like bytea, ... - canceling commands/queries - bulk copy - ... Connection Info ================ To connect, you must pass a connection string to pgsql.Connect(). Much as with the libpq conninfo parameter, values are optional, and may be overridden by environment variables at runtime, specifically: - PGPORT - port number - PGUSER - user name (defaults to postgres) - PGHOST - host name/address (defaults to localhost) - PGDATABASE - name of database (defaults to user name if not specified)
Documentation
¶
Overview ¶
The pgsql package implements a PostgreSQL frontend library. It is compatible with servers of version 7.4 and later.
Index ¶
- Constants
- type Conn
- func (conn *Conn) Close() (err error)
- func (conn *Conn) CopyFrom(command string, r io.Reader) (rowsAffected int64, err error)
- func (conn *Conn) Execute(command string, params ...*Parameter) (rowsAffected int64, err error)
- func (conn *Conn) Prepare(command string, params ...*Parameter) (stmt *Statement, err error)
- func (conn *Conn) Query(command string, params ...*Parameter) (rs *ResultSet, err error)
- func (conn *Conn) RuntimeParameter(name string) (value string, ok bool)
- func (conn *Conn) Scan(command string, args ...interface{}) (fetched bool, err error)
- func (conn *Conn) Status() ConnStatus
- func (conn *Conn) TransactionStatus() TransactionStatus
- func (conn *Conn) WithSavepoint(isolation IsolationLevel, f func() error) (err error)
- func (conn *Conn) WithTransaction(isolation IsolationLevel, f func() error) (err error)
- type ConnStatus
- type Error
- func (e *Error) Code() string
- func (e *Error) Detail() string
- func (e *Error) Error() string
- func (e *Error) File() string
- func (e *Error) Hint() string
- func (e *Error) InternalPosition() string
- func (e *Error) InternalQuery() string
- func (e *Error) Line() string
- func (e *Error) Message() string
- func (e *Error) Position() string
- func (e *Error) Routine() string
- func (e *Error) Severity() string
- func (e *Error) Where() string
- type IsolationLevel
- type LogLevel
- type Parameter
- type Pool
- type ResultSet
- func (rs *ResultSet) Any(ord int) (value interface{}, isNull bool, err error)
- func (rs *ResultSet) Bool(ord int) (value, isNull bool, err error)
- func (rs *ResultSet) Close() (err error)
- func (rs *ResultSet) Conn() *Conn
- func (rs *ResultSet) FetchNext() (hasRow bool, err error)
- func (rs *ResultSet) FieldCount() int
- func (rs *ResultSet) Float32(ord int) (value float32, isNull bool, err error)
- func (rs *ResultSet) Float64(ord int) (value float64, isNull bool, err error)
- func (rs *ResultSet) Int(ord int) (value int, isNull bool, err error)
- func (rs *ResultSet) Int16(ord int) (value int16, isNull bool, err error)
- func (rs *ResultSet) Int32(ord int) (value int32, isNull bool, err error)
- func (rs *ResultSet) Int64(ord int) (value int64, isNull bool, err error)
- func (rs *ResultSet) IsNull(ord int) (isNull bool, err error)
- func (rs *ResultSet) Name(ord int) (name string, err error)
- func (rs *ResultSet) NextResult() (hasResult bool, err error)
- func (rs *ResultSet) Ordinal(name string) int
- func (rs *ResultSet) Rat(ord int) (value *big.Rat, isNull bool, err error)
- func (rs *ResultSet) Scan(args ...interface{}) (err error)
- func (rs *ResultSet) ScanNext(args ...interface{}) (fetched bool, err error)
- func (rs *ResultSet) Statement() *Statement
- func (rs *ResultSet) String(ord int) (value string, isNull bool, err error)
- func (rs *ResultSet) Time(ord int) (value time.Time, isNull bool, err error)
- func (rs *ResultSet) TimeSeconds(ord int) (value int64, isNull bool, err error)
- func (rs *ResultSet) Type(ord int) (typ Type, err error)
- func (rs *ResultSet) Uint(ord int) (value uint, isNull bool, err error)
- func (rs *ResultSet) Uint16(ord int) (value uint16, isNull bool, err error)
- func (rs *ResultSet) Uint32(ord int) (value uint32, isNull bool, err error)
- func (rs *ResultSet) Uint64(ord int) (value uint64, isNull bool, err error)
- type Statement
- func (stmt *Statement) ActualCommand() string
- func (stmt *Statement) Close() (err error)
- func (stmt *Statement) Command() string
- func (stmt *Statement) Conn() *Conn
- func (stmt *Statement) Execute() (rowsAffected int64, err error)
- func (stmt *Statement) IsClosed() bool
- func (stmt *Statement) Parameter(name string) *Parameter
- func (stmt *Statement) Parameters() []*Parameter
- func (stmt *Statement) Query() (rs *ResultSet, err error)
- func (stmt *Statement) Scan(args ...interface{}) (fetched bool, err error)
- type TransactionStatus
- type Type
Constants ¶
const DEFAULT_IDLE_TIMEOUT = 300 // Seconds
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn struct {
LogLevel LogLevel
// contains filtered or unexported fields
}
Conn represents a PostgreSQL database connection.
func Connect ¶
Connect establishes a database connection.
Parameter settings in connStr have to be separated by whitespace and are expected in keyword = value form. Spaces around equal signs are optional. Use single quotes for empty values or values containing spaces.
Currently these keywords are supported:
host = Name of the host to connect to (default: localhost) port = Integer port number the server listens on (default: 5432) dbname = Database name (default: same as user) user = User to connect as password = Password for password based authentication methods timeout = Timeout in seconds, 0 or not specified disables timeout (default: 0)
func (*Conn) CopyFrom ¶
CopyFrom sends a `COPY table FROM STDIN` SQL command to the server and returns the number of rows affected.
func (*Conn) Execute ¶
Execute sends a SQL command to the server and returns the number of rows affected.
If the results of a query are needed, use the Query method instead.
func (*Conn) Prepare ¶
Prepare returns a new prepared Statement, optimized to be executed multiple times with different parameter values.
func (*Conn) Query ¶
Query sends a SQL query to the server and returns a ResultSet for row-by-row retrieval of the results.
The returned ResultSet must be closed before sending another query or command to the server over the same connection.
func (*Conn) RuntimeParameter ¶
RuntimeParameter returns the value of the specified runtime parameter.
If the value was successfully retrieved, ok is true, otherwise false.
func (*Conn) Scan ¶
Scan executes the command and scans the fields of the first row in the ResultSet, trying to store field values into the specified arguments.
The arguments must be of pointer types. If a row has been fetched, fetched will be true, otherwise false.
func (*Conn) Status ¶
func (conn *Conn) Status() ConnStatus
Status returns the current connection status.
func (*Conn) TransactionStatus ¶
func (conn *Conn) TransactionStatus() TransactionStatus
TransactionStatus returns the current transaction status of the connection.
func (*Conn) WithSavepoint ¶
func (conn *Conn) WithSavepoint(isolation IsolationLevel, f func() error) (err error)
WithSavepoint creates a transaction savepoint, if the connection is in an active transaction without errors, then calls f.
If f returns an error or panicks, the transaction is rolled back to the savepoint. If the connection is in a failed transaction when calling WithSavepoint, this function immediately returns with an error, without calling f. If no transaction is in progress, instead of creating a savepoint, a new transaction is started.
func (*Conn) WithTransaction ¶
func (conn *Conn) WithTransaction(isolation IsolationLevel, f func() error) (err error)
WithTransaction starts a new transaction, if none is in progress, then calls f.
If f returns an error or panicks, the transaction is rolled back, otherwise it is committed. If the connection is in a failed transaction when calling WithTransaction, this function immediately returns with an error, without calling f. In case of an active transaction without error, WithTransaction just calls f.
type ConnStatus ¶
type ConnStatus int
ConnStatus represents the status of a connection.
const ( StatusDisconnected ConnStatus = iota StatusReady StatusProcessingQuery StatusCopy )
func (ConnStatus) String ¶
func (s ConnStatus) String() string
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error contains detailed error information received from a PostgreSQL backend.
Many go-pgsql functions return an os.Error value. In case of a backend error, a type assertion as shown below gives you a *pgsql.Error with all details:
...
_, err := rs.FetchNext()
if err != nil {
if pgerr, ok := err.(*pgsql.Error); ok {
// Do something with pgerr
}
}
...
func (*Error) InternalPosition ¶
func (*Error) InternalQuery ¶
type IsolationLevel ¶
type IsolationLevel int
IsolationLevel represents the isolation level of a transaction.
const ( ReadCommittedIsolation IsolationLevel = iota SerializableIsolation )
func (IsolationLevel) String ¶
func (il IsolationLevel) String() string
type LogLevel ¶
type LogLevel int
LogLevel is used to control what is written to the log.
const ( // Log nothing. LogNothing LogLevel = iota // Log fatal errors. LogFatal // Log all errors. LogError // Log errors and warnings. LogWarning // Log errors, warnings and sent commands. LogCommand // Log errors, warnings, sent commands and additional debug info. LogDebug // Log everything. LogVerbose )
type Parameter ¶
type Parameter struct {
// contains filtered or unexported fields
}
Parameter is used to set the value of a parameter in a Statement.
func NewCustomTypeParameter ¶
NewCustomTypeParameter returns a new Parameter with the specified name and custom data type.
The value of customTypeName will be used to insert a type cast into the command text for each occurrence of the parameter.
This constructor can be used for enum type parameters. In that case the value provided to SetValue is expected to be a string.
func NewParameter ¶
NewParameter returns a new Parameter with the specified name and type.
func (*Parameter) CustomTypeName ¶
CustomTypeName returns the custom type name of the Parameter.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
A Pool manages a list of connections that can be safely used by multiple goroutines.
func NewPool ¶
func NewPool(connectParams string, minConns, maxConns int, idleTimeout time.Duration) (p *Pool, err error)
NewPool returns a new Pool that will create new connections on demand using connectParams, up to a maximum of maxConns outstanding connections. An error is returned if an initial connection cannot be created. Connections that have been idle for idleTimeout seconds will be automatically closed.
func (*Pool) Acquire ¶
Acquire returns the next available connection, or returns an error if it failed to create a new connection. When an Acquired connection has been finished with, it should be returned to the pool via Release.
type ResultSet ¶
type ResultSet struct {
// contains filtered or unexported fields
}
ResultSet reads the results of a query, row by row, and provides methods to retrieve field values of the current row.
Access is by 0-based field ordinal position.
func (*ResultSet) Any ¶
Any returns the value of the field with the specified ordinal as interface{}.
Types are mapped as follows:
PostgreSQL Go Bigint int64 Boolean bool Char string Date int64 Double float64 Integer int Numeric *big.Rat Real float Smallint int16 Text string Time time.Time TimeTZ time.Time Timestamp time.Time TimestampTZ time.Time Varchar string
func (*ResultSet) Close ¶
Close closes the ResultSet, so another query or command can be sent to the server over the same connection.
func (*ResultSet) FetchNext ¶
FetchNext reads the next row, if there is one.
In this case true is returned, otherwise false.
func (*ResultSet) FieldCount ¶
FieldCount returns the number of fields in the current result of the ResultSet.
func (*ResultSet) Float32 ¶
Float32 returns the value of the field with the specified ordinal as float32.
func (*ResultSet) Float64 ¶
Float64 returns the value of the field with the specified ordinal as float64.
func (*ResultSet) IsNull ¶
IsNull returns if the value of the field with the specified ordinal is null.
func (*ResultSet) NextResult ¶
NextResult moves the ResultSet to the next result, if there is one.
In this case true is returned, otherwise false. Statements support a single result only, use *Conn.Query if you need this functionality.
func (*ResultSet) Ordinal ¶
Ordinal returns the 0-based ordinal position of the field with the specified name, or -1 if the ResultSet has no field with such a name.
func (*ResultSet) Scan ¶
Scan scans the fields of the current row in the ResultSet, trying to store field values into the specified arguments.
The arguments must be of pointer types.
func (*ResultSet) ScanNext ¶
ScanNext scans the fields of the next row in the ResultSet, trying to store field values into the specified arguments.
The arguments must be of pointer types. If a row has been fetched, fetched will be true, otherwise false.
func (*ResultSet) String ¶
String returns the value of the field with the specified ordinal as string.
func (*ResultSet) Time ¶
Time returns the value of the field with the specified ordinal as *time.Time.
func (*ResultSet) TimeSeconds ¶
TimeSeconds returns the value of the field with the specified ordinal as int64.
func (*ResultSet) Uint16 ¶
Uint16 returns the value of the field with the specified ordinal as uint16.
type Statement ¶
type Statement struct {
// contains filtered or unexported fields
}
Statement is a means to efficiently execute a parameterized SQL command multiple times.
Call *Conn.Prepare to create a new prepared Statement.
func (*Statement) ActualCommand ¶
ActualCommand returns the actual command text that is sent to the server.
The original command is automatically adjusted if it contains parameters so it complies with what PostgreSQL expects. Refer to the return value of this method to make sense of the position information contained in many error messages.
func (*Statement) Execute ¶
Execute executes the Statement and returns the number of rows affected.
If the results of a query are needed, use the Query method instead.
func (*Statement) Parameter ¶
Parameter returns the Parameter with the specified name or nil, if the Statement has no Parameter with that name.
func (*Statement) Parameters ¶
Parameters returns a slice containing the parameters of the Statement.
func (*Statement) Query ¶
Query executes the Statement and returns a ResultSet for row-by-row retrieval of the results.
The returned ResultSet must be closed before sending another query or command to the server over the same connection.
type TransactionStatus ¶
type TransactionStatus byte
TransactionStatus represents the transaction status of a connection.
const ( NotInTransaction TransactionStatus = 'I' InTransaction TransactionStatus = 'T' InFailedTransaction TransactionStatus = 'E' )
func (TransactionStatus) String ¶
func (s TransactionStatus) String() string
type Type ¶
type Type int32
Type represents the PostgreSQL data type of fields and parameters.
const ( Custom Type = 0 Boolean Type = _BOOLOID Char Type = _CHAROID Date Type = _DATEOID Real Type = _FLOAT4OID Double Type = _FLOAT8OID Smallint Type = _INT2OID Integer Type = _INT4OID Bigint Type = _INT8OID Numeric Type = _NUMERICOID Text Type = _TEXTOID Time Type = _TIMEOID TimeTZ Type = _TIMETZOID Timestamp Type = _TIMESTAMPOID TimestampTZ Type = _TIMESTAMPTZOID Varchar Type = _VARCHAROID )
Source Files
Directories