Documentation
¶
Index ¶
- Constants
- Variables
- func IsDisconnected(err error) bool
- func NoRows(err error) bool
- type AdvisoryLock
- type Conn
- type ContextualTx
- func (tx *ContextualTx) Close() error
- func (tx *ContextualTx) Commit() error
- func (tx *ContextualTx) CopyFrom(tableName pgx.Identifier, columnNames []string, rowSrc pgx.CopyFromSource) (int64, error)
- func (tx *ContextualTx) Exec(sql string, arguments ...interface{}) (commandTag pgconn.CommandTag, err error)
- func (tx *ContextualTx) Prepare(name, sql string) (*pgconn.StatementDescription, error)
- func (tx *ContextualTx) Query(sql string, args ...interface{}) (pgx.Rows, error)
- func (tx *ContextualTx) QueryRow(sql string, args ...interface{}) pgx.Row
- func (tx *ContextualTx) Rollback() error
- func (tx *ContextualTx) SendBatch(b *pgx.Batch) pgx.BatchResults
- type DB
- func (db *DB) Begin(ctx context.Context) (Conn, error)
- func (db *DB) BeginWithTimeout(ctx context.Context) (*ContextualTx, error)
- func (db *DB) Close(context.Context) error
- func (db *DB) Commit(context.Context) error
- func (db *DB) Lock(ctx context.Context, id uint64) (AdvisoryLock, error)
- func (db *DB) Rollback(context.Context) error
- func (db *DB) SetTimeout(dur time.Duration)
- func (db *DB) Shutdown()
- func (db *DB) TryLock(ctx context.Context, id uint64) (AdvisoryLock, error)
- func (db *DB) WithTimeout(ctx context.Context) (context.Context, context.CancelFunc)
- type RowScanner
- type SessionAdvisoryLock
- type Tx
- func (tx *Tx) Begin(ctx context.Context) (Conn, error)
- func (tx *Tx) BeginWithTimeout(ctx context.Context) (*ContextualTx, error)
- func (tx *Tx) Close(ctx context.Context) error
- func (tx *Tx) Lock(ctx context.Context, id uint64) (AdvisoryLock, error)
- func (tx *Tx) SetTimeout(dur time.Duration)
- func (tx *Tx) TryLock(ctx context.Context, id uint64) (AdvisoryLock, error)
- func (tx *Tx) WithTimeout(ctx context.Context) (context.Context, context.CancelFunc)
- type TxAdvisoryLock
Constants ¶
const ( OperatorIntervention = "57000" QueryCanceled = "57014" AdminShutdown = "57P01" CrashShutdown = "57P02" CannotConnectNow = "57P03" DatabaseDropped = "57P04" IdleSessionTimeout = "57P05" )
PostgreSQL disconnect errors - https://www.postgresql.org/docs/current/errcodes-appendix.html
Variables ¶
var ( // Disconnects is the list of PostgreSQL error codes that indicate the connection failed. Disconnects = []string{ OperatorIntervention, QueryCanceled, AdminShutdown, CrashShutdown, CannotConnectNow, DatabaseDropped, IdleSessionTimeout, } )
var ErrLocked = errors.New("advisory lock already acquired")
ErrLocked returned if you try to acquire an advisory lock and it's already in use.
Functions ¶
func IsDisconnected ¶
IsDisconnected returns true if the error is a PostgreSQL disconnect error (SQLSTATE 57P01).
Types ¶
type AdvisoryLock ¶ added in v2.1.0
type AdvisoryLock interface {
Release() error
}
type Conn ¶
type Conn interface { // Begin starts a transaction. If Conn already represents a transaction, pgx will create a // savepoint instead. Begin(ctx context.Context) (Conn, error) // Commit the transaction. Does nothing if Conn is a *pgxpool.Pool. If the transaction is // a psuedo-transaction, i.e. a savepoint, releases the savepoint. Otherwise commits the // transaction. Commit(ctx context.Context) error // Rollback the transaction. Does nothing if Conn is a *pgxpool.Pool. Rollback(ctx context.Context) error // Close rolls back the transaction if this is a real transaction or rolls back to the // savepoint if this is a pseudo nested transaction. For a *pgxpool.Pool, this call is // ignored. // // Returns ErrTxClosed if the Conn is already closed, but is otherwise safe to call multiple // times. Hence, a defer conn.Close() is safe even if conn.Commit() will be called first in // a non-error condition. // // Any other failure of a real transaction will result in the connection being closed. Close(ctx context.Context) error CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, rowSrc pgx.CopyFromSource) (int64, error) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults Exec(ctx context.Context, sql string, arguments ...interface{}) (commandTag pgconn.CommandTag, err error) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row // Lock creates a session-wide advisory lock on a connection, and a transactional advisory // lock on a transaction. Will block until the lock is available. Returns an AdvsioryLock, // which must be released when you're done with the lock. Lock(ctx context.Context, id uint64) (AdvisoryLock, error) // TryLock tries to create a swssion-wide or transactional advisory lock, based on the // connection type. If successful, returns an AdvisoryLock which must be released when // you're done with it. If unsuccessful (lock is in use), returns an ErrLocked error. TryLock(ctx context.Context, id uint64) (AdvisoryLock, error) // WithTimeout returns a timeout context configured with the timeout setting configured on // the database connection pool. If ctx is already has an expiration, simply returns the // existing context. WithTimeout(ctx context.Context) (context.Context, context.CancelFunc) // SetTimeout sets the default timeout used for WithTimeout calls. SetTimeout(dur time.Duration) // BeginWithTimeout starts a custom transaction that manages the timeout context for you. // If Conn already represents a transaction, pgx will create a savepoint instead. This is // experimental; use at your own risk! BeginWithTimeout(ctx context.Context) (*ContextualTx, error) }
Conn abstracts the *pgxpool.Pool struct and the pgx.Tx interface into a common interface. This can be useful for building domain models more functionally, i.e the same function could be used for a single database query outside of a transaction, or included in a transaction with other function calls.
It's also useful for testing, as you can pass a transaction into any database-related function, don't commit, and simply Close() at the end of the test to clean up the database.
type ContextualTx ¶ added in v2.2.0
type ContextualTx struct { pgx.Tx // contains filtered or unexported fields }
ContextualTx is a prototype for starting a transaction using the default timeout and using the context on the transaction for any database calls from then on.
This does not support the hermes.Conn interface. At this point you can only use this transaction in a single function if you stick with hermes.Conn in your function parameters.
func (*ContextualTx) Close ¶ added in v2.2.0
func (tx *ContextualTx) Close() error
Close rolls back the transaction if this is a real transaction or rolls back to the savepoint if this is a pseudo nested transaction. It also cancels the context for the transaction.
Returns ErrTxClosed if the Conn is already closed, but is otherwise safe to call multiple times. Hence, a defer conn.Close() is safe even if conn.Commit() will be called first in a non-error condition.
Any other failure of a real transaction will result in the connection being closed.
func (*ContextualTx) Commit ¶ added in v2.2.0
func (tx *ContextualTx) Commit() error
Commit the transaction. Does nothing if Conn is a *pgxpool.Pool. If the transaction is a psuedo-transaction, i.e. a savepoint, releases the savepoint. Otherwise commits the transaction.
func (*ContextualTx) CopyFrom ¶ added in v2.2.0
func (tx *ContextualTx) CopyFrom(tableName pgx.Identifier, columnNames []string, rowSrc pgx.CopyFromSource) (int64, error)
CopyFrom uses the context on the transaction.
func (*ContextualTx) Exec ¶ added in v2.2.0
func (tx *ContextualTx) Exec(sql string, arguments ...interface{}) (commandTag pgconn.CommandTag, err error)
Exec uses the context on the transaction.
func (*ContextualTx) Prepare ¶ added in v2.2.0
func (tx *ContextualTx) Prepare(name, sql string) (*pgconn.StatementDescription, error)
Prepare uses the context on the transaction.
func (*ContextualTx) Query ¶ added in v2.2.0
func (tx *ContextualTx) Query(sql string, args ...interface{}) (pgx.Rows, error)
Query uses the context on the transaction.
func (*ContextualTx) QueryRow ¶ added in v2.2.0
func (tx *ContextualTx) QueryRow(sql string, args ...interface{}) pgx.Row
QueryRow uses the context on the transaction.
func (*ContextualTx) Rollback ¶ added in v2.2.0
func (tx *ContextualTx) Rollback() error
Rollback the transaction. Does nothing if Conn is a *pgxpool.Pool.
func (*ContextualTx) SendBatch ¶ added in v2.2.0
func (tx *ContextualTx) SendBatch(b *pgx.Batch) pgx.BatchResults
SendBatch uses the context on the transaction.
type DB ¶
DB wraps the *pgxpool.Pool and provides the missing hermes function wrappers.
func ConnectConfig ¶
ConnectConfig creates a pgx database connection pool based on a pool configuration and returns it.
func (*DB) BeginWithTimeout ¶ added in v2.2.0
func (db *DB) BeginWithTimeout(ctx context.Context) (*ContextualTx, error)
BeginWithTimeout starts a custom transaction that manages the timeout context for you. If Conn already represents a transaction, pgx will create a savepoint instead. This is experimental; use at your own risk!
func (*DB) Close ¶
Close does nothing. Since this Close method is meant to be used interchangably with transactions, it doesn't actually close anything, because we don't want to close the underlying database pool at the end of every non-transactional request. Instead, see DB.Shutdown.
func (*DB) Lock ¶ added in v2.1.0
Lock creates a session-wide advisory lock in the database. Call Release() to release the advisory lock.
func (*DB) SetTimeout ¶ added in v2.2.0
SetTimeout sets the default timeout for the database connection pool.
func (*DB) Shutdown ¶ added in v2.2.0
func (db *DB) Shutdown()
Shutdown the underlying pgx Pool. You should call this when your application is closing to release all the database pool connections.
func (*DB) TryLock ¶ added in v2.1.0
TryLock tries to create a session-wide advisory lock in the database. If successful, returns the advisory lock. If not, returns ErrLocked. If you acquire the lock, be sure to release it!
func (*DB) WithTimeout ¶ added in v2.2.0
WithTimeout creates a context with a timeout, assigning ctx as the parent of the timeout context. Returns the new context and its cancel function. The timeout is based on the configured database pool connection timeout (see `WithDefaultTimeout`).
Defaults to a 1 second timeout.
Be sure to call the cancel function when you're done to clean up any resources in use!
type RowScanner ¶
type RowScanner interface {
Scan(dest ...interface{}) error
}
RowScanner is a shared interface between pgx.Rows and pgx.Row
type SessionAdvisoryLock ¶ added in v2.1.0
type SessionAdvisoryLock struct { ID uint64 // contains filtered or unexported fields }
SessionAdvisoryLock creates a session-wide advisory lock.
func (*SessionAdvisoryLock) Release ¶ added in v2.1.0
func (lock *SessionAdvisoryLock) Release() error
Release the session-wide advisory lock.
type Tx ¶
type Tx struct { pgx.Tx // contains filtered or unexported fields }
Tx wraps the pgx.Tx interface and provides the missing hermes function wrappers.
func (*Tx) BeginWithTimeout ¶ added in v2.2.0
func (tx *Tx) BeginWithTimeout(ctx context.Context) (*ContextualTx, error)
BeginWithTimeout starts a custom transaction that manages the timeout context for you. If Conn already represents a transaction, pgx will create a savepoint instead. This is experimental; use at your own risk!
func (*Tx) Close ¶
Close rolls back the transaction if this is a real transaction or rolls back to the savepoint if this is a pseudo nested transaction.
Returns ErrTxClosed if the Conn is already closed, but is otherwise safe to call multiple times. Hence, a defer conn.Close() is safe even if conn.Commit() will be called first in a non-error condition.
Any other failure of a real transaction will result in the connection being closed.
func (*Tx) Lock ¶ added in v2.1.0
Lock creates an transactional advisory lock in the database. This lock will be released at the end of the transaction, on either commit or rollback. You may call AdvisoryLock.Release(), but it does nothing on this type of advisory lock.
func (*Tx) SetTimeout ¶ added in v2.2.0
SetTimeout sets the default timeout for a transaction. If never set, the transaction uses the timeout of the connection from the database pool.
func (*Tx) TryLock ¶ added in v2.1.0
TryLock creates an transactional advisory lock in the database. You may manually call Release() on the AdvisoryLock, or the lock will release automatically on commit or rollback.
func (*Tx) WithTimeout ¶ added in v2.2.0
WithTimeout creates a context with a timeout, assigning ctx as the parent of the timeout context. Returns the new context and its cancel function. The timeout is based on the configured database pool connection timeout (see `WithDefaultTimeout`).
Defaults to a 1 second timeout.
Be sure to call the cancel function when you're done to clean up any resources in use!
type TxAdvisoryLock ¶ added in v2.1.0
type TxAdvisoryLock struct {
ID uint64
}
TxAdvisoryLock is a placeholder so the Lock/Release functionality is the same for the hermes.Conn interface.
func (*TxAdvisoryLock) Release ¶ added in v2.1.0
func (lock *TxAdvisoryLock) Release() error
Release does nothing on a transactional advisory lock.