package pq

Import Path
	github.com/lib/pq (on go.dev)

Dependency Relation
	imports 33 packages, and imported by 4 packages


Involved Source Files

	      array.go
	      buf.go
	      conn.go
	      conn_go18.go
	      connector.go
	      copy.go
	
		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/lib/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/lib/pq/example/listen.

	      encode.go
	      error.go
	      notify.go
	      rows.go
	      ssl.go
	      ssl_permissions.go
	      url.go
	      user_posix.go
	      uuid.go


Package-Level Type Names (total 39, in which 21 are exported)


	/* sort exporteds by:  |  */
	
		ArrayDelimiter may be optionally implemented by driver.Valuer or sql.Scanner
		to override the array delimiter used by GenericArray.

		
			
				ArrayDelimiter returns the delimiter character(s) for this element's type.



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

		
			
				Scan implements the sql.Scanner interface.

			
				Value implements the driver.Valuer interface.

			
		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


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

		
			
				Scan implements the sql.Scanner interface.

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

			
		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


	
		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.

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

			
				Driver returnst the underlying driver of this Connector.

			
		
			*T : database/sql/driver.Connector
		
			func NewConnector(dsn string) (*Connector, error)


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

		
			( T) Dial(network, address string) (net.Conn, error)
			( T) DialTimeout(network, address string, timeout time.Duration) (net.Conn, error)
		
			
		
			 T : golang.org/x/net/proxy.Dialer
		
			func DialOpen(d Dialer, dsn string) (_ driver.Conn, err error)
			func NewDialListener(d Dialer, name string, minReconnectInterval time.Duration, maxReconnectInterval time.Duration, eventCallback EventCallbackType) *Listener
			


	
		DialerContext is the context-aware dialer interface.

		
			( T) DialContext(ctx context.Context, network, address string) (net.Conn, error)
		
			*crypto/tls.Dialer
			*golang.org/x/net/internal/socks.Dialer
			 golang.org/x/net/proxy.ContextDialer (interface)
			*golang.org/x/net/proxy.PerHost
			*net.Dialer
			
		
			 T : golang.org/x/net/proxy.ContextDialer


	
		Driver is the Postgres database driver.

		
			
				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.

		
			*T : database/sql/driver.Driver


	
		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

		
			Code ErrorCode
			Column string
			Constraint string
			DataTypeName string
			Detail string
			File string
			Hint string
			InternalPosition string
			InternalQuery string
			Line string
			Message string
			Position string
			Routine string
			Schema string
			Severity string
			Table string
			Where string
		
			( T) Error() string
			
				Fatal returns true if the Error Severity is fatal.

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

		
			*T : PGError
			 T : error
		
			


	
		ErrorClass is only the class part of an error code.

		
			
				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").

		
			func ErrorCode.Class() ErrorClass


	
		ErrorCode is a five-character error code.

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

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

			
				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.



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

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


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

		
			
				Scan implements the sql.Scanner interface.

			
				Value implements the driver.Valuer interface.

			
		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


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

		
			A interface{}
		
			
				Scan implements the sql.Scanner interface.

			
				Value implements the driver.Valuer interface.

			
		
			 T : database/sql.Scanner
			 T : database/sql/driver.Valuer


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

		
			
				Scan implements the sql.Scanner interface.

			
				Value implements the driver.Valuer interface.

			
		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


	
		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.

		
			
				Channel for receiving notifications from the database.  In some cases a
				nil value will be sent.  See section "Notifications" above.

			
		
			
				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.

			
				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.

			
				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.

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

			
				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.

			
				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.

			
		
			*T : io.Closer
		
			func NewDialListener(d Dialer, name string, minReconnectInterval time.Duration, maxReconnectInterval time.Duration, eventCallback EventCallbackType) *Listener
			func NewListener(name string, minReconnectInterval time.Duration, maxReconnectInterval time.Duration, eventCallback EventCallbackType) *Listener


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

		
			
		
			
				Close closes the connection.

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

			
				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.

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

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

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

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

			
		
			*T : io.Closer
		
			func NewListenerConn(name string, notificationChan chan<- *Notification) (*ListenerConn, error)
			
		
			


	
		ListenerEventType is an enumeration of listener event types.

		
			
		
			const ListenerEventConnected
			const ListenerEventConnectionAttemptFailed
			const ListenerEventDisconnected
			const ListenerEventReconnected


	
		Notification represents a single notification from the database.

		
			
				Process ID (PID) of the notifying postgres backend.

			
				Name of the channel the notification was sent on.

			
				Payload, or the empty string if unspecified.

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


	
		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.

		
			Time time.Time
			
				// Valid is true if Time is not NULL

		
			
				Scan implements the Scanner interface.

			
				Value implements the driver Valuer interface.

		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


	
		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.

		
			( T) Error() string
			( T) Fatal() bool
			( T) Get(k byte) (v string)
		
			*Error
		
			 T : error


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

		
			
				Scan implements the sql.Scanner interface.

			
				Value implements the driver.Valuer interface.

			
		
			*T : database/sql.Scanner
			 T : database/sql/driver.Valuer


	


Package-Level Functions (total 61, in which 15 are exported)


	
		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.


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


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


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


	
		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.


	
		FormatTimestamp formats t into Postgres' text format for timestamps.


	
		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.


	
		NewDialListener is like NewListener but it takes a Dialer.


	
		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.


	
		NewListenerConn creates a new ListenerConn. Use NewListener instead.


	
		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.


	
		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.


	
		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


	
		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.


	
		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.


	


Package-Level Variables (total 29, in which 7 are exported)


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


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


	
		Common error types


	
		Common error types


	
		Common error types


	
		Common error types


	


Package-Level Constants (total 24, in which 11 are exported)


	
		Error severities


	
		Error severities


	
		Error severities


	
		Error severities


	
		Error severities


	
		Error severities


	
		Error severities


	
		ListenerEventConnected is emitted only when the database connection
		has been initially initialized. The err argument of the callback
		will always be nil.


	
		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.


	
		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.


	
		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.