stdlib

package
v4.18.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 9, 2024 License: MIT Imports: 16 Imported by: 1,735

Documentation

Overview

Package stdlib is the compatibility layer from pgx to database/sql.

A database/sql connection can be established through sql.Open.

db, err := sql.Open("pgx", "postgres://pgx_md5:secret@localhost:5432/pgx_test?sslmode=disable")
if err != nil {
	return err
}

Or from a DSN string.

db, err := sql.Open("pgx", "user=postgres password=secret host=localhost port=5432 database=pgx_test sslmode=disable")
if err != nil {
	return err
}

Or a pgx.ConnConfig can be used to set configuration not accessible via connection string. In this case the pgx.ConnConfig must first be registered with the driver. This registration returns a connection string which is used with sql.Open.

connConfig, _ := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
connConfig.Logger = myLogger
connStr := stdlib.RegisterConnConfig(connConfig)
db, _ := sql.Open("pgx", connStr)

pgx uses standard PostgreSQL positional parameters in queries. e.g. $1, $2. It does not support named parameters.

db.QueryRow("select * from users where id=$1", userID)

In Go 1.13 and above (*sql.Conn) Raw() can be used to get a *pgx.Conn from the standard database/sql.DB connection pool. This allows operations that use pgx specific functionality.

// Given db is a *sql.DB
conn, err := db.Conn(context.Background())
if err != nil {
	// handle error from acquiring connection from DB pool
}

err = conn.Raw(func(driverConn interface{}) error {
	conn := driverConn.(*stdlib.Conn).Conn() // conn is a *pgx.Conn
	// Do pgx specific stuff with conn
	conn.CopyFrom(...)
	return nil
})
if err != nil {
	// handle error that occurred while using *pgx.Conn
}

Index

Constants

This section is empty.

Variables

View Source
var ErrNotPgx = errors.New("not pgx *sql.DB")

Functions

func AcquireConn

func AcquireConn(db *sql.DB) (*pgx.Conn, error)

AcquireConn acquires a *pgx.Conn from database/sql connection pool. It must be released with ReleaseConn.

In Go 1.13 this functionality has been incorporated into the standard library in the db.Conn.Raw() method.

func GetConnector added in v4.16.0

func GetConnector(config pgx.ConnConfig, opts ...OptionOpenDB) driver.Connector

func GetDefaultDriver added in v4.2.0

func GetDefaultDriver() driver.Driver

GetDefaultDriver returns the driver initialized in the init function and used when the pgx driver is registered.

func OpenDB

func OpenDB(config pgx.ConnConfig, opts ...OptionOpenDB) *sql.DB

func RandomizeHostOrderFunc added in v4.12.0

func RandomizeHostOrderFunc(ctx context.Context, connConfig *pgx.ConnConfig) error

RandomizeHostOrderFunc is a BeforeConnect hook that randomizes the host order in the provided connConfig, so that a new host becomes primary each time. This is useful to distribute connections for multi-master databases like CockroachDB. If you use this you likely should set https://golang.org/pkg/database/sql/#DB.SetConnMaxLifetime as well to ensure that connections are periodically rebalanced across your nodes.

func RegisterConnConfig added in v4.2.0

func RegisterConnConfig(c *pgx.ConnConfig) string

RegisterConnConfig registers a ConnConfig and returns the connection string to use with Open.

func ReleaseConn

func ReleaseConn(db *sql.DB, conn *pgx.Conn) error

ReleaseConn releases a *pgx.Conn acquired with AcquireConn.

func UnregisterConnConfig added in v4.2.0

func UnregisterConnConfig(connStr string)

UnregisterConnConfig removes the ConnConfig registration for connStr.

Types

type Conn

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

func (*Conn) Begin

func (c *Conn) Begin() (driver.Tx, error)

func (*Conn) BeginTx

func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

func (*Conn) CheckNamedValue added in v4.8.0

func (c *Conn) CheckNamedValue(*driver.NamedValue) error

func (*Conn) Close

func (c *Conn) Close() error

func (*Conn) Conn added in v4.7.0

func (c *Conn) Conn() *pgx.Conn

Conn returns the underlying *pgx.Conn

func (*Conn) ExecContext

func (c *Conn) ExecContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Result, error)

func (*Conn) Ping

func (c *Conn) Ping(ctx context.Context) error

func (*Conn) Prepare

func (c *Conn) Prepare(query string) (driver.Stmt, error)

func (*Conn) PrepareContext

func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

func (*Conn) QueryContext

func (c *Conn) QueryContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Rows, error)

func (*Conn) ResetSession added in v4.12.0

func (c *Conn) ResetSession(ctx context.Context) error

type Driver

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

func (*Driver) Open

func (d *Driver) Open(name string) (driver.Conn, error)

func (*Driver) OpenConnector added in v4.3.0

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

type OptionOpenDB

type OptionOpenDB func(*connector)

OptionOpenDB options for configuring the driver when opening a new db pool.

func OptionAfterConnect

func OptionAfterConnect(ac func(context.Context, *pgx.Conn) error) OptionOpenDB

OptionAfterConnect provides a callback for after connect.

func OptionBeforeConnect added in v4.12.0

func OptionBeforeConnect(bc func(context.Context, *pgx.ConnConfig) error) OptionOpenDB

OptionBeforeConnect provides a callback for before connect. It is passed a shallow copy of the ConnConfig that will be used to connect, so only its immediate members should be modified.

func OptionResetSession added in v4.12.0

func OptionResetSession(rs func(context.Context, *pgx.Conn) error) OptionOpenDB

OptionResetSession provides a callback that can be used to add custom logic prior to executing a query on the connection if the connection has been used before. If ResetSessionFunc returns ErrBadConn error the connection will be discarded.

type Rows

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

func (*Rows) Close

func (r *Rows) Close() error

func (*Rows) ColumnTypeDatabaseTypeName

func (r *Rows) ColumnTypeDatabaseTypeName(index int) string

ColumnTypeDatabaseTypeName returns the database system type name. If the name is unknown the OID is returned.

func (*Rows) ColumnTypeLength

func (r *Rows) ColumnTypeLength(index int) (int64, bool)

ColumnTypeLength returns the length of the column type if the column is a variable length type. If the column is not a variable length type ok should return false.

func (*Rows) ColumnTypePrecisionScale

func (r *Rows) ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)

ColumnTypePrecisionScale should return the precision and scale for decimal types. If not applicable, ok should be false.

func (*Rows) ColumnTypeScanType

func (r *Rows) ColumnTypeScanType(index int) reflect.Type

ColumnTypeScanType returns the value type that can be used to scan types into.

func (*Rows) Columns

func (r *Rows) Columns() []string

func (*Rows) Next

func (r *Rows) Next(dest []driver.Value) error

type Stmt

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

func (*Stmt) Close

func (s *Stmt) Close() error

func (*Stmt) Exec

func (s *Stmt) Exec(argsV []driver.Value) (driver.Result, error)

func (*Stmt) ExecContext

func (s *Stmt) ExecContext(ctx context.Context, argsV []driver.NamedValue) (driver.Result, error)

func (*Stmt) NumInput

func (s *Stmt) NumInput() int

func (*Stmt) Query

func (s *Stmt) Query(argsV []driver.Value) (driver.Rows, error)

func (*Stmt) QueryContext

func (s *Stmt) QueryContext(ctx context.Context, argsV []driver.NamedValue) (driver.Rows, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL