pq

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2024 License: MIT Imports: 45 Imported by: 0

README

pq - A pure Go openGauss driver for Go's database/sql package

fork from github/lib/pq

Install

go get gitee.com/opengauss/openGauss-connector-go-pq

What's the difference of libpq for openGauss

When using original libpq go driver to access openGauss, the following error will be reported.

pq: Invalid username/password,login denied.

The reason is that openGauss default user connection password authentication method is sha256, which is a unique encryption method. Although openGauss configuration can be modified by the following methods to support native libpq connection.

  1. Set the openGauss initialization parameter password_encryption_type.

    alter system set password_encryption_type=0;

  2. Set pg_hba.conf to allow md5 password verification: host all test 0.0.0.0/0 md5

  3. Create a new user in database, then connect by this user.

We still prefer to use a more secure encryption method like sha256, so the modified libpq can be directly compatible with sha256.

Features

  • Adapt openGauss SHA256/SM3 password authentication
  • Support for multiple host defined connections
  • SSL
    • sslmode
    • sslrootcert
    • sslcert
    • sslkey
    • sslinline This parameter specifies the sslkey/sslcert is a string not a file
    • sslpassword This parameter specifies the password for the secret key specified in sslkey
  • Handles bad connections for database/sql
  • Scan time.Time correctly (i.e. timestamp[tz], time[tz], date)
  • Scan binary blobs correctly (i.e. bytea)
  • Package for hstore support
  • COPY FROM support
  • pq.ParseURL for converting urls to connection strings for sql.Open.
  • Many libpq compatible environment variables
  • Unix socket support
  • Notifications: LISTEN/NOTIFY
  • pgpass support
  • GSS (Kerberos) auth

Multiple Hosts

example multi_ip

postgres docsLIBPQ-MULTIPLE-HOSTS

  • Support to define the master and slave addresses at the same time, automatically select the main library connection, and automatically connect to the new master library when a switch occurs.
  • The target_session_attrs parameter in the connection character can only define read-write (default configuration), and there is a problem with the configuration as read-only
  • target_session_attrs
    • any (default)
    • read-write
    • read-only
    • primary
    • standby
    • prefer-standby
postgres://gaussdb:secret@foo,bar,baz/mydb?sslmode=disable&target_session_attrs=primary&connect_timeout=1
postgres://gaussdb:secret@foo:1,bar:2,baz:3/mydb?sslmode=disable&target_session_attrs=primary&connect_timeout=1
user=gaussdb password=secret host=foo,bar,baz port=5432 dbname=mydb sslmode=disable target_session_attrs=primary connect_timeout=1
user=gaussdb password=secret host=foo,bar,baz port=5432,5432,5433 dbname=mydb sslmode=disable target_session_attrs=primary connect_timeout=1

Example

import (
 "database/sql"

 _ "gitee.com/opengauss/openGauss-connector-go-pq"
)

func main() {
 connStr := "host=127.0.0.1 port=5432 user=gaussdb password=test@1234 dbname=postgres sslmode=disable"
 db, err := sql.Open("opengauss", connStr)
 if err != nil {
  log.Fatal(err)
 }
 var date string
 err = db.QueryRow("select current_date ").Scan(&date)
 if err != nil {
  log.Fatal(err)
 }
 fmt.Println(date)
}

Tests

go test is used for testing. See TESTS.md for more details.

Documentation

Overview

Package pq is a pure Go Postgres driver for the database/sql package.

In most cases clients will use the database/sql package instead of using this package directly. For example: 

import (
	"database/sql"

	_ "github.com/felixji7/openGauss-connector-go-pq"
)

func main() {
	connStr := "user=pqgotest dbname=pqgotest sslmode=verify-full"
	db, err := sql.Open("postgres", connStr)
	if err != nil {
		log.Fatal(err)
	}

	age := 21
	rows, err := db.Query("SELECT name FROM users WHERE age = $1", age)
	…
}

You can also connect to a database using a URL. For example: 

connStr := "postgres://pqgotest:password@localhost/pqgotest?sslmode=verify-full"
db, err := sql.Open("postgres", connStr)

Connection String Parameters

Similarly to libpq, when establishing a connection using pq you are expected to supply a connection string containing zero or more parameters. A subset of the connection parameters supported by libpq are also supported by pq. Additionally, pq also lets you specify run-time parameters (such as search_path or work_mem) directly in the connection string. This is different from libpq, which does not allow run-time parameters in the connection string, instead requiring you to supply them in the options parameter.

For compatibility with libpq, the following special connection parameters are supported:

  • dbname - The name of the database to connect to
  • user - The user to sign in as
  • password - The user's password
  • host - The host to connect to. Values that start with / are for unix domain sockets. (default is localhost)
  • port - The port to bind to. (default is 5432)
  • sslmode - Whether or not to use SSL (default is require, this is not the default for libpq)
  • fallback_application_name - An application_name to fall back to if one isn't provided.
  • connect_timeout - Maximum wait for connection, in seconds. Zero or not specified means wait indefinitely.
  • sslcert - Cert file location. The file must contain PEM encoded data.
  • sslkey - Key file location. The file must contain PEM encoded data.
  • sslrootcert - The location of the root certificate file. The file must contain PEM encoded data.

Valid values for sslmode are:

  • disable - No SSL
  • require - Always SSL (skip verification)
  • verify-ca - Always SSL (verify that the certificate presented by the server was signed by a trusted CA)
  • verify-full - Always SSL (verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate)

See http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING for more information about connection string parameters.

Use single quotes for values that contain whitespace: 

"user=pqgotest password='with spaces'"

A backslash will escape the next character in values: 

"user=space\ man password='it\'s valid'"

Note that the connection parameter client_encoding (which sets the text encoding for the connection) may be set but must be "UTF8", matching with the same rules as Postgres. It is an error to provide any other value.

In addition to the parameters listed above, any run-time parameter that can be set at backend start time can be set in the connection string. For more information, see http://www.postgresql.org/docs/current/static/runtime-config.html.

Most environment variables as specified at http://www.postgresql.org/docs/current/static/libpq-envars.html supported by libpq are also supported by pq. If any of the environment variables not supported by pq are set, pq will panic during connection establishment. Environment variables have a lower precedence than explicitly provided connection parameters.

The pgpass mechanism as described in http://www.postgresql.org/docs/current/static/libpq-pgpass.html is supported, but on Windows PGPASSFILE must be specified explicitly.

Queries

database/sql does not dictate any specific format for parameter markers in query strings, and pq uses the Postgres-native ordinal markers, as shown above. The same marker can be reused for the same parameter: 

rows, err := db.Query(`SELECT name FROM users WHERE favorite_fruit = $1
	OR age BETWEEN $2 AND $2 + 3`, "orange", 64)

pq does not support the LastInsertId() method of the Result type in database/sql. To return the identifier of an INSERT (or UPDATE or DELETE), use the Postgres RETURNING clause with a standard Query or QueryRow call: 

var userid int
err := db.QueryRow(`INSERT INTO users(name, favorite_fruit, age)
	VALUES('beatrice', 'starfruit', 93) RETURNING id`).Scan(&userid)

For more details on RETURNING, see the Postgres documentation: 

http://www.postgresql.org/docs/current/static/sql-insert.html
http://www.postgresql.org/docs/current/static/sql-update.html
http://www.postgresql.org/docs/current/static/sql-delete.html

For additional instructions on querying see the documentation for the database/sql package.

Data Types

Parameters pass through driver.DefaultParameterConverter before they are handled by this package. When the binary_parameters connection option is enabled, []byte values are sent directly to the backend as data in binary format.

This package returns the following types for values from the PostgreSQL backend:

  • integer types smallint, integer, and bigint are returned as int64
  • floating-point types real and double precision are returned as float64
  • character types char, varchar, and text are returned as string
  • temporal types date, time, timetz, timestamp, and timestamptz are returned as time.Time
  • the boolean type is returned as bool
  • the bytea type is returned as []byte

All other types are returned directly from the backend as []byte values in text format.

Errors

pq may return errors of type *pq.Error which can be interrogated for error details: 

if err, ok := err.(*pq.Error); ok {
    fmt.Println("pq error:", err.Code.Name())
}

See the pq.Error type for details.

Bulk imports

You can perform bulk imports by preparing a statement returned by pq.CopyIn (or pq.CopyInSchema) in an explicit transaction (sql.Tx). The returned statement handle can then be repeatedly "executed" to copy data into the target table. After all data has been processed you should call Exec() once with no arguments to flush all buffered data. Any call to Exec() might return an error which should be handled appropriately, but because of the internal buffering an error returned by Exec() might not be related to the data passed in the call that failed.

CopyIn uses COPY FROM internally. It is not possible to COPY outside of an explicit transaction in pq.

Usage example: 

txn, err := db.Begin()
if err != nil {
	log.Fatal(err)
}

stmt, err := txn.Prepare(pq.CopyIn("users", "name", "age"))
if err != nil {
	log.Fatal(err)
}

for _, user := range users {
	_, err = stmt.Exec(user.Name, int64(user.Age))
	if err != nil {
		log.Fatal(err)
	}
}

_, err = stmt.Exec()
if err != nil {
	log.Fatal(err)
}

err = stmt.Close()
if err != nil {
	log.Fatal(err)
}

err = txn.Commit()
if err != nil {
	log.Fatal(err)
}

Notifications

PostgreSQL supports a simple publish/subscribe model over database connections. See http://www.postgresql.org/docs/current/static/sql-notify.html for more information about the general mechanism.

To start listening for notifications, you first have to open a new connection to the database by calling NewListener. This connection can not be used for anything other than LISTEN / NOTIFY. Calling Listen will open a "notification channel"; once a notification channel is open, a notification generated on that channel will effect a send on the Listener.Notify channel. A notification channel will remain open until Unlisten is called, though connection loss might result in some notifications being lost. To solve this problem, Listener sends a nil pointer over the Notify channel any time the connection is re-established following a connection loss. The application can get information about the state of the underlying connection by setting an event callback in the call to NewListener.

A single Listener can safely be used from concurrent goroutines, which means that there is often no need to create more than one Listener in your application. However, a Listener is always connected to a single database, so you will need to create a new Listener instance for every database you want to receive notifications in.

The channel name in both Listen and Unlisten is case sensitive, and can contain any characters legal in an identifier (see http://www.postgresql.org/docs/current/static/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS for more information). Note that the channel name will be truncated to 63 bytes by the PostgreSQL server.

You can find a complete, working example of Listener usage at https://godoc.org/github.com/felixji7/openGauss-connector-go-pq/example/listen.

Kerberos Support

If you need support for Kerberos authentication, add the following to your main package: 

import "github.com/felixji7/openGauss-connector-go-pq/auth/kerberos"

func init() {
	pq.RegisterGSSProvider(func() (pq.Gss, error) { return kerberos.NewGSS() })
}

This package is in a separate module so that users who don't need Kerberos don't have to download unnecessary dependencies.

When imported, additional connection string parameters are supported:

  • krbsrvname - GSS (Kerberos) service name when constructing the SPN (default is `postgres`). This will be combined with the host to form the full SPN: `krbsrvname/host`.
  • krbspn - GSS (Kerberos) SPN. This takes priority over `krbsrvname` if present.

Index

Examples

Constants

View Source 
const (
	AuthReqOk          = 0
	AUTH_REQ_KRB4      = 1
	AUTH_REQ_KRB5      = 2
	AuthReqPassword    = 3
	AUTH_REQ_CRYPT     = 4
	AuthReqMd5         = 5
	AUTH_REQ_SCM       = 6
	AuthReqGss         = 7
	AuthReqGssContinue = 8
	AUTH_REQ_SSPI      = 9
	AuthReqSha256      = 10
	AuthReqMd5Sha256   = 11
	AuthReqSm3         = 13

	PlainPassword  = 0
	Md5Password    = 1
	Sha256Password = 2

	Sm3Password = 3

	ClientEncoding        = "client_encoding"
	ServerEncoding        = "server_encoding"
	ServerVersion         = "server_version"
	TimeZone              = "TimeZone"
	DefaultClientEncoding = "UTF-8"
)
View Source 
const (
	Efatal   = "FATAL"
	Epanic   = "PANIC"
	Ewarning = "WARNING"
	Enotice  = "NOTICE"
	Edebug   = "DEBUG"
	Einfo    = "INFO"
	Elog     = "LOG"
)

Error severities

View Source 
const (
	LogLevelTrace = 6
	LogLevelDebug = 5
	LogLevelInfo  = 4
	LogLevelWarn  = 3
	LogLevelError = 2
	LogLevelNone  = 1
)

The values for log levels are chosen such that the zero value means that no log level was specified.

Variables

View Source 
var (
	ErrNotSupported              = errors.New("pq: Unsupported command")
	ErrInFailedTransaction       = errors.New("pq: Could not complete operation in a failed transaction")
	ErrSSLNotSupported           = errors.New("pq: SSL is not enabled on the server")
	ErrSSLKeyUnknownOwnership    = errors.New("pq: Could not get owner information for private key, may not be properly protected")
	ErrSSLKeyHasWorldPermissions = errors.New("pq: Private key has world access. Permissions should be u=rw,g=r (0640) if owned by root, or u=rw (0600), or less")

	ErrCouldNotDetectUsername = errors.New("pq: Could not detect default username. Please provide one explicitly")
)

Common error types

View Source 
var ErrChannelAlreadyOpen = errors.New("pq: channel is already open")

ErrChannelAlreadyOpen is returned from Listen when a channel is already open.

View Source 
var ErrChannelNotOpen = errors.New("pq: channel is not open")

ErrChannelNotOpen is returned from Unlisten when a channel is not open.

Functions

func Array 

func Array(a interface{}) interface {
	driver.Valuer
	sql.Scanner
}

Array returns the optimal driver.Valuer and sql.Scanner for an array or slice of any dimension.

For example: 

db.Query(`SELECT * FROM t WHERE id = ANY($1)`, pq.Array([]int{235, 401}))

var x []sql.NullInt64
db.QueryRow(`SELECT ARRAY[235, 401]`).Scan(pq.Array(&x))

Scanning multi-dimensional arrays is not supported. Arrays where the lower bound is not one (such as `[0:0]={1}') are not supported.

func ConnectorNoticeHandler 

func ConnectorNoticeHandler(c driver.Connector) func(*Error)

ConnectorNoticeHandler returns the currently set notice handler, if any. If the given connector is not a result of ConnectorWithNoticeHandler, nil is returned.

func ConnectorNotificationHandler 

func ConnectorNotificationHandler(c driver.Connector) func(*Notification)

ConnectorNotificationHandler returns the currently set notification handler, if any. If the given connector is not a result of ConnectorWithNotificationHandler, nil is returned.

func CopyIn 

func CopyIn(table string, columns ...string) string

CopyIn creates a COPY FROM statement which can be prepared with Tx.Prepare(). The target table should be visible in search_path.

func CopyInSchema 

func CopyInSchema(schema, table string, columns ...string) string

CopyInSchema creates a COPY FROM statement which can be prepared with Tx.Prepare().

func DeregisterTLSConfig 

func DeregisterTLSConfig(key string)

DeregisterTLSConfig removes the tls.Config associated with key.

func DialOpen 

func DialOpen(d Dialer, dsn string) (_ driver.Conn, err error)

DialOpen opens a new connection to the database using a dialer.

func EnableInfinityTs 

func EnableInfinityTs(negative time.Time, positive time.Time)

EnableInfinityTs controls the handling of Postgres' "-infinity" and "infinity" "timestamp"s.

If EnableInfinityTs is not called, "-infinity" and "infinity" will return []byte("-infinity") and []byte("infinity") respectively, and potentially cause error "sql: Scan error on column index 0: unsupported driver -> Scan pair: []uint8 -> *time.Time", when scanning into a time.Time value.

Once EnableInfinityTs has been called, all connections created using this driver will decode Postgres' "-infinity" and "infinity" for "timestamp", "timestamp with time zone" and "date" types to the predefined minimum and maximum times, respectively. When encoding time.Time values, any time which equals or precedes the predefined minimum time will be encoded to "-infinity". Any values at or past the maximum time will similarly be encoded to "infinity".

If EnableInfinityTs is called with negative >= positive, it will panic. Calling EnableInfinityTs after a connection has been established results in undefined behavior. If EnableInfinityTs is called more than once, it will panic.

func FormatTimestamp 

func FormatTimestamp(t time.Time) []byte

FormatTimestamp formats t into Postgres' text format for timestamps.

func Md5Sha256encode 

func Md5Sha256encode(password, random64code string, salt []byte) []byte
	Md5Sha256encode
   public static byte[] Md5Sha256encode(String password, String random64code, byte salt[]) {
       MessageDigest md;
       byte[] temp_digest, pass_digest;
       byte[] hex_digest = new byte[35];
       try {
           StringBuilder stringBuilder = new StringBuilder("");
           byte[] K = MD5Digest.generateKFromPBKDF2(password, random64code);
           byte[] server_key = MD5Digest.getKeyFromHmac(K, "Sever Key".getBytes("UTF-8"));
           byte[] client_key = MD5Digest.getKeyFromHmac(K, "Client Key".getBytes("UTF-8"));
           byte[] stored_key = MD5Digest.sha256(client_key);
           stringBuilder.append(random64code);
           stringBuilder.append(MD5Digest.bytesToHexString(server_key));
           stringBuilder.append(MD5Digest.bytesToHexString(stored_key));
           String EncryptString = stringBuilder.toString();
           md = MessageDigest.getInstance("MD5");
           md.update(EncryptString.getBytes("UTF-8"));
           md.update(salt);
           pass_digest = md.digest();
           bytesToHex(pass_digest, hex_digest, 3, 16);
           hex_digest[0] = (byte) 'm';
           hex_digest[1] = (byte) 'd';
           hex_digest[2] = (byte) '5';
       } catch (NoSuchAlgorithmException | UnsupportedEncodingException e) {
           LOGGER.info("MD5_SHA256encode failed. ", e);
       } catch (Exception e) {
           LOGGER.info("MD5_SHA256encode failed. ", e);
       }
       return hex_digest;
   }

func NetworkAddress 

func NetworkAddress(host string, port uint16) (network, address string)

NetworkAddress converts a PostgreSQL host and port into network and address suitable for use with net.Dial.

func NoticeHandler 

func NoticeHandler(c driver.Conn) func(*Error)

NoticeHandler returns the notice handler on the given connection, if any. A runtime panic occurs if c is not a pq connection. This is rarely used directly, use ConnectorNoticeHandler and ConnectorWithNoticeHandler instead.

func Open 

func Open(dsn string) (_ driver.Conn, err error)

Open opens a new connection to the database. dsn is a connection string. Most users should only use it through database/sql package from the standard library.

func ParseTimestamp 

func ParseTimestamp(currentLocation *time.Location, str string) (time.Time, error)

ParseTimestamp parses Postgres' text format. It returns a time.Time in currentLocation iff that time's offset agrees with the offset sent from the Postgres server. Otherwise, ParseTimestamp returns a time.Time with the fixed offset offset provided by the Postgres server.

func ParseURL 

func ParseURL(url string) (string, error)

ParseURL no longer needs to be used by clients of this library since supplying a URL as a connection string to sql.Open() is now supported: 

sql.Open("postgres", "postgres://bob:secret@1.2.3.4:5432/mydb?sslmode=verify-full")

It remains exported here for backwards-compatibility.

ParseURL converts a url to a connection string for driver.Open. Example: 

"postgres://bob:secret@1.2.3.4:5432/mydb?sslmode=verify-full"

converts to: 

"user=bob password=secret host=1.2.3.4 port=5432 dbname=mydb sslmode=verify-full"

A minimal example: 

"postgres://"

This will be blank, causing driver.Open to use all of the defaults

func ParseURLToMap 

func ParseURLToMap(connString string) (map[string]string, error)

func QuoteIdentifier 

func QuoteIdentifier(name string) string

QuoteIdentifier quotes an "identifier" (e.g. a table or a column name) to be used as part of an SQL statement. For example: 

tblname := "my_table"
data := "my_data"
quoted := pq.QuoteIdentifier(tblname)
err := db.Exec(fmt.Sprintf("INSERT INTO %s VALUES ($1)", quoted), data)

Any double quotes in name will be escaped. The quoted identifier will be case sensitive when used in a query. If the input string contains a zero byte, the result will be truncated immediately before it.

func QuoteLiteral 

func QuoteLiteral(literal string) string

QuoteLiteral quotes a 'literal' (e.g. a parameter, often used to pass literal to DDL and other statements that do not accept parameters) to be used as part of an SQL statement. For example: 

exp_date := pq.QuoteLiteral("2023-01-05 15:00:00Z")
err := db.Exec(fmt.Sprintf("CREATE ROLE my_user VALID UNTIL %s", exp_date))

Any single quotes in name will be escaped. Any backslashes (i.e. "\") will be replaced by two backslashes (i.e. "\\") and the C-style escape identifier that PostgreSQL provides ('E') will be prepended to the string.

func RFC5802Algorithm 

func RFC5802Algorithm(password string, random64code string, token string, serverSignature string, serverIteration int, method string) []byte

RFC5802Algorithm 

public static byte[] RFC5802Algorithm(
        String password, String random64code, String token, String server_signature, int server_iteration) {
    byte[] h = null;
    byte[] result = null;
    try {
        byte[] K = generateKFromPBKDF2(password, random64code, server_iteration);
        byte[] server_key = getKeyFromHmac(K, "Sever Key".getBytes("UTF-8"));
        byte[] client_key = getKeyFromHmac(K, "Client Key".getBytes("UTF-8"));
        byte[] stored_key = null;
        if (getIsSha256()) {
        	stored_key = sha256(client_key);
        } else {
        	stored_key = sm3(client_key);
        }
        byte[] tokenbyte = hexStringToBytes(token);
        byte[] client_signature = getKeyFromHmac(server_key, tokenbyte);
        if (server_signature != null && !server_signature.equals(bytesToHexString(client_signature))) return new byte[0];
        byte[] hmac_result = getKeyFromHmac(stored_key, tokenbyte);
        h = XOR_between_password(hmac_result, client_key, client_key.length);
        result = new byte[h.length * 2];
        bytesToHex(h, result, 0, h.length);
    } catch (Exception e) {
        LOGGER.info("RFC5802Algorithm failed. " + e.toString());
    }
    return result;
}

func RegisterGSSProvider 

func RegisterGSSProvider(newGssArg NewGSSFunc)

RegisterGSSProvider registers a GSS authentication provider. For example, if you need to use Kerberos to authenticate with your server, add this to your main package: 

import "github.com/felixji7/openGauss-connector-go-pq/auth/kerberos"

func init() {
	pq.RegisterGSSProvider(func() (pq.GSS, error) { return kerberos.NewGSS() })
}

func RegisterTLSConfig 

func RegisterTLSConfig(key string, config *tls.Config) error

func SetNoticeHandler 

func SetNoticeHandler(c driver.Conn, handler func(*Error))

SetNoticeHandler sets the given notice handler on the given connection. A runtime panic occurs if c is not a pq connection. A nil handler may be used to unset it. This is rarely used directly, use ConnectorNoticeHandler and ConnectorWithNoticeHandler instead.

Note: Notice handlers are executed synchronously by pq meaning commands won't continue to be processed until the handler returns.

func SetNotificationHandler 

func SetNotificationHandler(c driver.Conn, handler func(*Notification))

SetNotificationHandler sets the given notification handler on the given connection. A runtime panic occurs if c is not a pq connection. A nil handler may be used to unset it.

Note: Notification handlers are executed synchronously by pq meaning commands won't continue to be processed until the handler returns.

func ValidateConnectTargetSessionAttrsPrimary 

func ValidateConnectTargetSessionAttrsPrimary(cn *conn) error

func ValidateConnectTargetSessionAttrsReadOnly 

func ValidateConnectTargetSessionAttrsReadOnly(cn *conn) error

func ValidateConnectTargetSessionAttrsReadWrite 

func ValidateConnectTargetSessionAttrsReadWrite(cn *conn) error

func ValidateConnectTargetSessionAttrsStandby 

func ValidateConnectTargetSessionAttrsStandby(cn *conn) error

func XorBetweenPassword 

func XorBetweenPassword(password1 []byte, password2 []byte, length int) []byte

Types

type ArrayDelimiter 

type ArrayDelimiter interface {
	// ArrayDelimiter returns the delimiter character(s) for this element's type.
	ArrayDelimiter() string
}

ArrayDelimiter may be optionally implemented by driver.Valuer or sql.Scanner to override the array delimiter used by GenericArray.

type BoolArray 

type BoolArray []bool

BoolArray represents a one-dimensional array of the PostgreSQL boolean type.

func (*BoolArray) Scan 

func (a *BoolArray) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (BoolArray) Value 

func (a BoolArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type ByteaArray 

type ByteaArray [][]byte

ByteaArray represents a one-dimensional array of the PostgreSQL bytea type.

func (*ByteaArray) Scan 

func (a *ByteaArray) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (ByteaArray) Value 

func (a ByteaArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface. It uses the "hex" format which is only supported on PostgreSQL 9.0 or newer.

type Config 

type Config struct {
	Host           string // host (e.g. localhost) or absolute path to unix domain socket directory (e.g. /private/tmp)
	Port           uint16
	Database       string
	User           string
	Password       string
	TLSConfig      *tls.Config // nil disables TLS
	ConnectTimeout time.Duration
	DialFunc       DialFunc   // e.g. net.Dialer.DialContext
	LookupFunc     LookupFunc // e.g. net.Resolver.LookupHost
	// BuildFrontend  BuildFrontendFunc
	RuntimeParams map[string]string // Run-time parameters to set on connection as session default values (e.g. search_path or application_name)
	GssAPIParams  map[string]string
	Fallbacks     []*FallbackConfig

	ValidateConnect ValidateConnectFunc

	Logger   Logger
	LogLevel LogLevel
	// contains filtered or unexported fields
}

Config is the settings used to establish a connection to a PostgreSQL server. It must be created by ParseConfig. A manually initialized Config will cause ConnectConfig to panic.

func ParseConfig 

func ParseConfig(connString string) (*Config, error)

ParseConfig builds a *Config with similar behavior to the PostgreSQL standard C library libpq. It uses the same defaults as libpq (e.g. port=5432) and understands most PG* environment variables. ParseConfig closely matches the parsing behavior of libpq. connString may either be in URL format or keyword = value format (DSN style). See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be empty to only read from the environment. If a password is not supplied it will attempt to read the .pgpass file. 

# Example DSN
user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca

# Example URL
postgres://jack:secret@pg.example.com:5432/mydb?sslmode=verify-ca

The returned *Config may be modified. However, it is strongly recommended that any configuration that can be done through the connection string be done there. In particular the fields Host, Port, TLSConfig, and Fallbacks can be interdependent (e.g. TLSConfig needs knowledge of the host to validate the server certificate). These fields should not be modified individually. They should all be modified or all left unchanged.

ParseConfig supports specifying multiple hosts in similar manner to libpq. Host and port may include comma separated values that will be tried in order. This can be used as part of a high availability system. See https://www.postgresql.org/docs/11/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS for more information. 

# Example URL
postgres://jack:secret@foo.example.com:5432,bar.example.com:5432/mydb

ParseConfig currently recognizes the following environment variable and their parameter key word equivalents passed via database URL or DSN: 

PGHOST
PGPORT
PGDATABASE
PGUSER
PGPASSWORD
PGPASSFILE
PGSERVICE
PGSERVICEFILE
PGSSLMODE
PGSSLCERT
PGSSLKEY
PGSSLROOTCERT
PGAPPNAME
PGCONNECT_TIMEOUT
PGTARGETSESSIONATTRS

See http://www.postgresql.org/docs/11/static/libpq-envars.html for details on the meaning of environment variables.

See https://www.postgresql.org/docs/11/libpq-connect.html#LIBPQ-PARAMKEYWORDS for parameter key word names. They are usually but not always the environment variable name downcased and without the "PG" prefix.

Important Security Notes:

ParseConfig tries to match libpq behavior with regard to PGSSLMODE. This includes defaulting to "prefer" behavior if not set.

See http://www.postgresql.org/docs/11/static/libpq-ssl.html#LIBPQ-SSL-PROTECTION for details on what level of security each sslmode provides.

The sslmode "prefer" (the default), sslmode "allow", and multiple hosts are implemented via the Fallbacks field of the Config struct. If TLSConfig is manually changed it will not affect the fallbacks. For example, in the case of sslmode "prefer" this means it will first try the main Config settings which use TLS, then it will try the fallback which does not use TLS. This can lead to an unexpected unencrypted connection if the main TLS config is manually changed later but the unencrypted fallback is present. Ensure there are no stale fallbacks when manually setting TLCConfig.

Other known differences with libpq:

If a host name resolves into multiple addresses, libpq will try all addresses. pgconn will only try the first.

When multiple hosts are specified, libpq allows them to have different passwords set via the .pgpass file. pgconn does not.

In addition, ParseConfig accepts the following options: 

min_read_buffer_size
	The minimum size of the internal read buffer. Default 8192.
servicefile
	libpq only reads servicefile from the PGSERVICEFILE environment variable. ParseConfig accepts servicefile as a
	part of the connection string.

func (*Config) Copy 

func (c *Config) Copy() *Config

Copy returns a deep copy of the config that is safe to use and modify. The only exception is the TLSConfig field: according to the tls.Config docs it must not be modified after creation.

type Connector 

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

Connector represents a fixed configuration for the pq driver with a given name. Connector satisfies the database/sql/driver Connector interface and can be used to create any number of DB Conn's via the database/sql OpenDB function.

See https://golang.org/pkg/database/sql/driver/#Connector. See https://golang.org/pkg/database/sql/#OpenDB.

func NewConnector 

func NewConnector(dsn string) (*Connector, error)

NewConnector returns a connector for the pq driver in a fixed configuration with the given dsn. The returned connector can be used to create any number of equivalent Conn's. The returned connector is intended to be used with database/sql.OpenDB.

See https://golang.org/pkg/database/sql/driver/#Connector. See https://golang.org/pkg/database/sql/#OpenDB.

Example 
name := ""
connector, err := pq.NewConnector(name)
if err != nil {
	fmt.Println(err)
	return
}
db := sql.OpenDB(connector)
defer db.Close()

// Use the DB
txn, err := db.Begin()
if err != nil {
	fmt.Println(err)
	return
}
txn.Rollback()

Output:

func NewConnectorConfig 

func NewConnectorConfig(config *Config) (*Connector, error)

NewConnectorConfig establishes a connection to a openGauss server using config. config must have been constructed with ParseConfig.

func (*Connector) Connect 

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

Connect returns a connection to the database using the fixed configuration of this Connector. Context is not used.

func (*Connector) Driver 

func (c *Connector) Driver() driver.Driver

Driver returns the underlying driver of this Connector.

type DialFunc 

type DialFunc func(ctx context.Context, network, addr string) (net.Conn, error)

DialFunc is a function that can be used to connect to a PostgreSQL server.

type Dialer 

type Dialer interface {
	Dial(network, address string) (net.Conn, error)
	DialTimeout(network, address string, timeout time.Duration) (net.Conn, error)
}

Dialer is the dialer interface. It can be used to obtain more control over how pq creates network connections.

type DialerContext 

type DialerContext interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

DialerContext is the context-aware dialer interface.

type Driver 

type Driver struct{}

Driver is the Postgres database driver.

func (Driver) Open 

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

Open opens a new connection to the database. name is a connection string. Most users should only use it through database/sql package from the standard library.

type Error 

type Error struct {
	Severity         string
	Code             ErrorCode
	Message          string
	Detail           string
	Hint             string
	Position         string
	InternalPosition string
	InternalQuery    string
	Where            string
	Schema           string
	Table            string
	Column           string
	DataTypeName     string
	Constraint       string
	File             string
	Line             string
	Routine          string
}

Error represents an error communicating with the server.

See http://www.postgresql.org/docs/current/static/protocol-error-fields.html for details of the fields

func (Error) Error 

func (err Error) Error() string

func (*Error) Fatal 

func (err *Error) Fatal() bool

Fatal returns true if the Error Severity is fatal.

func (*Error) Get 

func (err *Error) Get(k byte) (v string)

Get implements the legacy PGError interface. New code should use the fields of the Error struct directly.

func (*Error) SQLState 

func (err *Error) SQLState() string

SQLState returns the SQLState of the error.

type ErrorClass 

type ErrorClass string

ErrorClass is only the class part of an error code.

func (ErrorClass) Name 

func (ec ErrorClass) Name() string

Name returns the condition name of an error class. It is equivalent to the condition name of the "standard" error code (i.e. the one having the last three characters "000").

type ErrorCode 

type ErrorCode string

ErrorCode is a five-character error code.

func (ErrorCode) Class 

func (ec ErrorCode) Class() ErrorClass

Class returns the error class, e.g. "28".

See http://www.postgresql.org/docs/9.3/static/errcodes-appendix.html for details.

func (ErrorCode) Name 

func (ec ErrorCode) Name() string

Name returns a more human friendly rendering of the error code, namely the "condition name".

See http://www.postgresql.org/docs/9.3/static/errcodes-appendix.html for details.

func (ErrorCode) String 

func (ec ErrorCode) String() string

type EventCallbackType 

type EventCallbackType func(event ListenerEventType, err error)

EventCallbackType is the event callback type. See also ListenerEventType constants' documentation.

type FallbackConfig 

type FallbackConfig struct {
	Host      string // host (e.g. localhost) or path to unix domain socket directory (e.g. /private/tmp)
	Port      uint16
	TLSConfig *tls.Config // nil disables TLS
}

FallbackConfig is additional settings to attempt a connection with when the primary Config fails to establish a network connection. It is used for TLS fallback such as sslmode=prefer and high availability (HA) connections.

type Float32Array 

type Float32Array []float32

Float32Array represents a one-dimensional array of the PostgreSQL double precision type.

func (*Float32Array) Scan 

func (a *Float32Array) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Float32Array) Value 

func (a Float32Array) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type Float64Array 

type Float64Array []float64

Float64Array represents a one-dimensional array of the PostgreSQL double precision type.

func (*Float64Array) Scan 

func (a *Float64Array) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Float64Array) Value 

func (a Float64Array) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type GSS 

type GSS interface {
	GetInitToken(host string, service string) ([]byte, error)
	GetInitTokenFromSpn(spn string) ([]byte, error)
	Continue(inToken []byte) (done bool, outToken []byte, err error)
}

GSS provides GSSAPI authentication (e.g., Kerberos).

type GenericArray 

type GenericArray struct{ A interface{} }

GenericArray implements the driver.Valuer and sql.Scanner interfaces for an array or slice of any dimension.

func (GenericArray) Scan 

func (a GenericArray) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (GenericArray) Value 

func (a GenericArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type Int32Array 

type Int32Array []int32

Int32Array represents a one-dimensional array of the PostgreSQL integer types.

func (*Int32Array) Scan 

func (a *Int32Array) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Int32Array) Value 

func (a Int32Array) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type Int64Array 

type Int64Array []int64

Int64Array represents a one-dimensional array of the PostgreSQL integer types.

func (*Int64Array) Scan 

func (a *Int64Array) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Int64Array) Value 

func (a Int64Array) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type Listener 

type Listener struct {
	// Channel for receiving notifications from the database.  In some cases a
	// nil value will be sent.  See section "Notifications" above.
	Notify chan *Notification
	// contains filtered or unexported fields
}

Listener provides an interface for listening to notifications from a PostgreSQL database. For general usage information, see section "Notifications".

Listener can safely be used from concurrently running goroutines.

func NewDialListener 

func NewDialListener(d Dialer,
	name string,
	minReconnectInterval time.Duration,
	maxReconnectInterval time.Duration,
	eventCallback EventCallbackType) *Listener

NewDialListener is like NewListener but it takes a Dialer.

func NewListener 

func NewListener(name string,
	minReconnectInterval time.Duration,
	maxReconnectInterval time.Duration,
	eventCallback EventCallbackType) *Listener

NewListener creates a new database connection dedicated to LISTEN / NOTIFY.

name should be set to a connection string to be used to establish the database connection (see section "Connection String Parameters" above).

minReconnectInterval controls the duration to wait before trying to re-establish the database connection after connection loss. After each consecutive failure this interval is doubled, until maxReconnectInterval is reached. Successfully completing the connection establishment procedure resets the interval back to minReconnectInterval.

The last parameter eventCallback can be set to a function which will be called by the Listener when the state of the underlying database connection changes. This callback will be called by the goroutine which dispatches the notifications over the Notify channel, so you should try to avoid doing potentially time-consuming operations from the callback.

func (*Listener) Close 

func (l *Listener) Close() error

Close disconnects the Listener from the database and shuts it down. Subsequent calls to its methods will return an error. Close returns an error if the connection has already been closed.

func (*Listener) Listen 

func (l *Listener) Listen(channel string) error

Listen starts listening for notifications on a channel. Calls to this function will block until an acknowledgement has been received from the server. Note that Listener automatically re-establishes the connection after connection loss, so this function may block indefinitely if the connection can not be re-established.

Listen will only fail in three conditions:

  1. The channel is already open. The returned error will be ErrChannelAlreadyOpen.
  2. The query was executed on the remote server, but PostgreSQL returned an error message in response to the query. The returned error will be a pq.Error containing the information the server supplied.
  3. Close is called on the Listener before the request could be completed.

The channel name is case-sensitive.

func (*Listener) NotificationChannel 

func (l *Listener) NotificationChannel() <-chan *Notification

NotificationChannel returns the notification channel for this listener. This is the same channel as Notify, and will not be recreated during the life time of the Listener.

func (*Listener) Ping 

func (l *Listener) Ping() error

Ping the remote server to make sure it's alive. Non-nil return value means that there is no active connection.

func (*Listener) Unlisten 

func (l *Listener) Unlisten(channel string) error

Unlisten removes a channel from the Listener's channel list. Returns ErrChannelNotOpen if the Listener is not listening on the specified channel. Returns immediately with no error if there is no connection. Note that you might still get notifications for this channel even after Unlisten has returned.

The channel name is case-sensitive.

func (*Listener) UnlistenAll 

func (l *Listener) UnlistenAll() error

UnlistenAll removes all channels from the Listener's channel list. Returns immediately with no error if there is no connection. Note that you might still get notifications for any of the deleted channels even after UnlistenAll has returned.

type ListenerConn 

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

ListenerConn is a low-level interface for waiting for notifications. You should use Listener instead.

func NewListenerConn 

func NewListenerConn(name string, notificationChan chan<- *Notification) (*ListenerConn, error)

NewListenerConn creates a new ListenerConn. Use NewListener instead.

func (*ListenerConn) Close 

func (l *ListenerConn) Close() error

Close closes the connection.

func (*ListenerConn) Err 

func (l *ListenerConn) Err() error

Err returns the reason the connection was closed. It is not safe to call this function until l.Notify has been closed.

func (*ListenerConn) ExecSimpleQuery 

func (l *ListenerConn) ExecSimpleQuery(q string) (executed bool, err error)

ExecSimpleQuery executes a "simple query" (i.e. one with no bindable parameters) on the connection. The possible return values are:

  1. "executed" is true; the query was executed to completion on the database server. If the query failed, err will be set to the error returned by the database, otherwise err will be nil.
  2. If "executed" is false, the query could not be executed on the remote server. err will be non-nil.

After a call to ExecSimpleQuery has returned an executed=false value, the connection has either been closed or will be closed shortly thereafter, and all subsequently executed queries will return an error.

func (*ListenerConn) Listen 

func (l *ListenerConn) Listen(channel string) (bool, error)

Listen sends a LISTEN query to the server. See ExecSimpleQuery.

func (*ListenerConn) Ping 

func (l *ListenerConn) Ping() error

Ping the remote server to make sure it's alive. Non-nil error means the connection has failed and should be abandoned.

func (*ListenerConn) Unlisten 

func (l *ListenerConn) Unlisten(channel string) (bool, error)

Unlisten sends an UNLISTEN query to the server. See ExecSimpleQuery.

func (*ListenerConn) UnlistenAll 

func (l *ListenerConn) UnlistenAll() (bool, error)

UnlistenAll sends an `UNLISTEN *` query to the server. See ExecSimpleQuery.

type ListenerEventType 

type ListenerEventType int

ListenerEventType is an enumeration of listener event types. 

const (
	// ListenerEventConnected is emitted only when the database connection
	// has been initially initialized. The err argument of the callback
	// will always be nil.
	ListenerEventConnected ListenerEventType = iota

	// ListenerEventDisconnected is emitted after a database connection has
	// been lost, either because of an error or because Close has been
	// called. The err argument will be set to the reason the database
	// connection was lost.
	ListenerEventDisconnected

	// ListenerEventReconnected is emitted after a database connection has
	// been re-established after connection loss. The err argument of the
	// callback will always be nil. After this event has been emitted, a
	// nil pq.Notification is sent on the Listener.Notify channel.
	ListenerEventReconnected

	// ListenerEventConnectionAttemptFailed is emitted after a connection
	// to the database was attempted, but failed. The err argument will be
	// set to an error describing why the connection attempt did not
	// succeed.
	ListenerEventConnectionAttemptFailed
)

type LogLevel 

type LogLevel int

LogLevel represents the conn logging level. See LogLevel* constants for possible values.

func LogLevelFromString 

func LogLevelFromString(s string) (LogLevel, error)

LogLevelFromString converts log level string to constant

Valid levels: 

trace
debug
info
warn
error
none

func (LogLevel) String 

func (ll LogLevel) String() string

type Logger 

type Logger interface {
	// Log a message at the given level with data key/value pairs. data may be nil.
	Log(ctx context.Context, level LogLevel, msg string, data map[string]interface{})
}

Logger is the interface used to get logging from conn internals. 

var DefaultLogger Logger = NewPrintfLogger(LogLevelDebug)

func NewPrintfLogger 

func NewPrintfLogger(level LogLevel) Logger

type LookupFunc 

type LookupFunc func(ctx context.Context, host string) (addrs []string, err error)

LookupFunc is a function that can be used to lookup IPs addrs from host.

type NewGSSFunc 

type NewGSSFunc func() (GSS, error)

NewGSSFunc creates a GSS authentication provider, for use with RegisterGSSProvider.

type NoticeHandlerConnector 

type NoticeHandlerConnector struct {
	driver.Connector
	// contains filtered or unexported fields
}

NoticeHandlerConnector wraps a regular connector and sets a notice handler on it.

func ConnectorWithNoticeHandler 

func ConnectorWithNoticeHandler(c driver.Connector, handler func(*Error)) *NoticeHandlerConnector

ConnectorWithNoticeHandler creates or sets the given handler for the given connector. If the given connector is a result of calling this function previously, it is simply set on the given connector and returned. Otherwise, this returns a new connector wrapping the given one and setting the notice handler. A nil notice handler may be used to unset it.

The returned connector is intended to be used with database/sql.OpenDB.

Note: Notice handlers are executed synchronously by pq meaning commands won't continue to be processed until the handler returns.

Example 
//go:build go1.10
// +build go1.10

package main

import (
	"database/sql"
	"fmt"
	"log"
	"os"
)

func getTestDsn() (string, error) {
	dsn := os.Getenv("TEST_CONN_STRING")
	if dsn == "" {
		return "", fmt.Errorf("not define TEST_CONN_STRING env")
	}
	return dsn, nil
}

func main() {
	name, err := getTestDsn()
	if err != nil {
		log.Fatal(err)
	}
	// Base connector to wrap
	base, err := pq.NewConnector(name)
	if err != nil {
		log.Fatal(err)
	}
	// Wrap the connector to simply print out the message
	connector := pq.ConnectorWithNoticeHandler(base, func(notice *pq.Error) {
		fmt.Println("Notice sent: " + notice.Message)
	})
	db := sql.OpenDB(connector)
	defer db.Close()
	// Raise a notice
	sql := "DO language plpgsql $$ BEGIN RAISE NOTICE 'test notice'; END $$"
	if _, err := db.Exec(sql); err != nil {
		log.Fatal(err)
	}
}

Output:

Notice sent: test notice

func (*NoticeHandlerConnector) Connect 

func (n *NoticeHandlerConnector) Connect(ctx context.Context) (driver.Conn, error)

Connect calls the underlying connector's connect method and then sets the notice handler.

type Notification 

type Notification struct {
	// Process ID (PID) of the notifying postgres backend.
	BePid int
	// Name of the channel the notification was sent on.
	Channel string
	// Payload, or the empty string if unspecified.
	Extra string
}

Notification represents a single notification from the database.

type NotificationHandlerConnector 

type NotificationHandlerConnector struct {
	driver.Connector
	// contains filtered or unexported fields
}

NotificationHandlerConnector wraps a regular connector and sets a notification handler on it.

func ConnectorWithNotificationHandler 

func ConnectorWithNotificationHandler(c driver.Connector, handler func(*Notification)) *NotificationHandlerConnector

ConnectorWithNotificationHandler creates or sets the given handler for the given connector. If the given connector is a result of calling this function previously, it is simply set on the given connector and returned. Otherwise, this returns a new connector wrapping the given one and setting the notification handler. A nil notification handler may be used to unset it.

The returned connector is intended to be used with database/sql.OpenDB.

Note: Notification handlers are executed synchronously by pq meaning commands won't continue to be processed until the handler returns.

func (*NotificationHandlerConnector) Connect 

func (n *NotificationHandlerConnector) Connect(ctx context.Context) (driver.Conn, error)

Connect calls the underlying connector's connect method and then sets the notification handler.

type NullTime 

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL
}

NullTime represents a time.Time that may be null. NullTime implements the sql.Scanner interface so it can be used as a scan destination, similar to sql.NullString.

func (*NullTime) Scan 

func (nt *NullTime) Scan(value interface{}) error

Scan implements the Scanner interface.

func (NullTime) Value 

func (nt NullTime) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type PGError 

type PGError interface {
	Error() string
	Fatal() bool
	Get(k byte) (v string)
}

PGError is an interface used by previous versions of pq. It is provided only to support legacy code. New code should use the Error type.

type StringArray 

type StringArray []string

StringArray represents a one-dimensional array of the PostgreSQL character types.

func (*StringArray) Scan 

func (a *StringArray) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (StringArray) Value 

func (a StringArray) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type ValidateConnectFunc 

type ValidateConnectFunc func(conn *conn) error

Source Files

View all Source files

Directories

Path Synopsis
listen
Package listen is a self-contained Go program which uses the LISTEN / NOTIFY mechanism to avoid polling the database while waiting for more work to arrive.
 Package listen is a self-contained Go program which uses the LISTEN / NOTIFY mechanism to avoid polling the database while waiting for more work to arrive.
multi_ip
Package oid contains OID constants as defined by the Postgres server.
 Package oid contains OID constants as defined by the Postgres server.
Package pgpassfile is a parser PostgreSQL .pgpass files.
 Package pgpassfile is a parser PostgreSQL .pgpass files.
Package pgservicefile is a parser for PostgreSQL service files (e.g.
 Package pgservicefile is a parser for PostgreSQL service files (e.g.
Package scram implements a SCRAM-{SHA-1,etc} client per RFC5802.
 Package scram implements a SCRAM-{SHA-1,etc} client per RFC5802.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.