stdlib package - github.com/jackc/pgx/v5/stdlib - Go Packages (original) (raw)

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 keyword/value 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 from a *pgxpool.Pool.

pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL")) if err != nil { return err }

db := stdlib.OpenDBFromPool(pool)

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.Tracer = &tracelog.TraceLog{Logger: myLogger, LogLevel: tracelog.LogLevelInfo} connStr := stdlib.RegisterConnConfig(connConfig) db, _ := sql.Open("pgx", connStr)

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

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

(*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 any) 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 }

PostgreSQL Specific Data Types

The pgtype package provides support for PostgreSQL specific types. *pgtype.Map.SQLScanner is an adapter that makes these types usable as a sql.Scanner.

m := pgtype.NewMap() var a []int64 err := db.QueryRow("select '{1,2,3}'::bigint[]").Scan(m.SQLScanner(&a))

This section is empty.

This section is empty.

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

GetPoolConnector creates a new driver.Connector from the given *pgxpool.Pool. By using this be sure to set the maximum idle connections of the *sql.DB created with this connector to zero since they must be managed from the *pgxpool.Pool. This is required to avoid acquiring all the connections from the pgxpool and starving any direct users of the pgxpool.

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

OpenDBFromPool creates a new *sql.DB from the given *pgxpool.Pool. Note that this method automatically sets the maximum number of idle connections in *sql.DB to zero, since they must be managed from the *pgxpool.Pool. This is required to avoid acquiring all the connections from the pgxpool and starving any direct users of the pgxpool. Note that closing the returned *sql.DB will not close the *pgxpool.Pool.

func RandomizeHostOrderFunc

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(c *pgx.ConnConfig) string

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

func UnregisterConnConfig(connStr string)

UnregisterConnConfig removes the ConnConfig registration for connStr.

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

Conn returns the underlying *pgx.Conn

type OptionOpenDB func(*connector)

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

OptionAfterConnect provides a callback for after connect. Used only if db is opened with *pgx.ConnConfig.

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. Used only if db is opened with *pgx.ConnConfig.

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.

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

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

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

func (s *Stmt) NumInput() int