stdlib

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
}

A DriverConfig can be used to further configure the connection process. This allows configuring TLS configuration, setting a custom dialer, logging, and setting an AfterConnect hook.

driverConfig := stdlib.DriverConfig{
	ConnConfig: pgx.ConnConfig{
		Logger:   logger,
	},
	AfterConnect: func(c *pgx.Conn) error {
		// Ensure all connections have this temp table available
		_, err := c.Exec("create temporary table foo(...)")
		return err
	},
}

stdlib.RegisterDriverConfig(&driverConfig)

db, err := sql.Open("pgx", driverConfig.ConnectionString("postgres://pgx_md5:secret@127.0.0.1:5432/pgx_test"))
if err != nil {
	return err
}

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)

AcquireConn and ReleaseConn acquire and release a *pgx.Conn from the standard database/sql.DB connection pool. This allows operations that must be performed on a single connection without running in a transaction, and it supports operations that use pgx specific functionality.

conn, err := stdlib.AcquireConn(db)
if err != nil {
	return err
}
defer stdlib.ReleaseConn(db, conn)

// do stuff with pgx.Conn

It also can be used to enable a fast path for pgx while preserving compatibility with other drivers and database.

conn, err := stdlib.AcquireConn(db)
if err == nil {
	// fast path with pgx
	// ...
	// release conn when done
	stdlib.ReleaseConn(db, conn)
} else {
	// normal path for other drivers and databases
}