pqxx::connection Class Reference

Connection to a database. More...

#include <connection.hxx>

Public Member Functions
Connecting to a database
You connect to a database by creating a connection object. (Except advanced users can also connect asynchronously using the connecting class; in that case creating the connection is only the beginning. In the normal case, however, creating a connection and connecting to a database are the same thing.) If the attempt to connect fails, you will not get a connection object; the constructor will fail with a pqxx::broken_connection exception. You can control each of the details of how to connect (hostname, username, database name, etc.) in up to 4 ways. All are optional, and you can combine some or all of them: You can pass connection parameters to the constructor. You can pass a connection string to the constructor. There are environment variables you can set: PGHOST, PGUSER, etc. Each has a built-in default value. For each individual item, the connection will take the value from the first item in this list that defines it. Note All of the strings that you pass into the constructor must be zero-terminated, i.e. they must end in a byte with value zero, like classic C-style strings. That's because libpqxx passes them on to the underlying C library, libpq. A C++ std::string is guaranteed to have a terminating zero, so that's fine. However a std::string_view does not, and that's why libpqxx has pqxx::zview. A zview is like a std::string_view except you promise that there's a terminating zero. Connection parameters are individual key/value pairs of strings. You can pass these as a std::map, or as a std::vector of std::pair, or in pretty much any other form that boils down to "a series of pairs of zero-terminated strings." If you pass the same parameter multiple times with different values in the same series of parameters, the latest value applies. The connection parameters are documented here: https://postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS Connection strings can be in one of two formats: a custom key-value format, or a RFC 3986 Uniform Resource Identifier (URI). They are documented here: https://postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING Environment variables for controlling how you connect are documented here: https://postgresql.org/docs/current/libpq-envars.html
	connection (sl loc=sl::current())
template<pqxx::ZString STRING, ZKey_ZValues MAPPING>
	connection (STRING const &connection_string, MAPPING &&params=empty_params_t(), sl=sl::current())
	Connect to a database with both connection string and parameter pairs. More...
template<pqxx::ZString STRING>
	connection (STRING const &connection_string, sl loc=sl::current())
	Connect to a database, passing a connection string. More...
template<ZKey_ZValues MAPPING>
	connection (MAPPING &&params, sl loc=sl::current())
	Connect to a database, passing connection parameters. More...
	connection (connection &&rhs, sl=sl::current())
	Move constructor. More...
	~connection ()
connection &	operator= (connection &&rhs)
	Move assignment. More...
	connection (connection const &)=delete
connection &	operator= (connection const &)=delete
bool	is_open () const noexcept
	Is this connection open at the moment? More...
PQXX_ZARGS void	process_notice (char const[]) noexcept
	Invoke notice processor function. The message should end in newline. More...
void	process_notice (zview) noexcept
	Invoke notice processor function. Newline at end is recommended. More...
void	trace (std::FILE *) noexcept
	Enable tracing to a given output stream, or nullptr to disable. More...
Connection properties
These are probably not of great interest, since most are derived from information supplied by the client program itself, but they are included for completeness. The connection needs to be currently active for these to work.
char const *	dbname () const noexcept
	Name of the database to which we're connected, if any. More...
char const *	username () const noexcept
	Database user ID under which we are connected, if any. More...
PQXX_PURE char const *	hostname () const noexcept
	Database server address, if given. More...
PQXX_PURE char const *	port () const noexcept
	Server port number on which we are connected to the database. More...
PQXX_PURE std::optional< int >	port_number (sl loc=sl::current()) const
	Server port number on which we are connected to the database, if any. More...
PQXX_PURE int	backendpid () const &noexcept
	Process ID for backend process, or 0 if inactive. More...
PQXX_PURE int	sock () const &noexcept
	Socket currently used for connection, or -1 for none. More...
PQXX_PURE int	protocol_version () const noexcept
	What version of the PostgreSQL protocol is this connection using? More...
PQXX_PURE int	server_version () const noexcept
	What version of the PostgreSQL server are we connected to? More...
Text encoding
std::string	get_client_encoding (sl loc=sl::current()) const
	Get client-side character encoding, by name. More...
void	set_client_encoding (zview encoding, sl loc=sl::current()) &
	Set client-side character encoding, by name. More...
PQXX_ZARGS void	set_client_encoding (char const encoding[], sl=sl::current()) &
	Set client-side character encoding, by name. More...
int	encoding_id (sl=sl::current()) const
	Get the connection's encoding, as a PostgreSQL-defined code. More...
encoding_group	get_encoding_group (sl loc=sl::current()) const
	Read the curent client encoding's pqxx::encoding_group. More...
template<typename TYPE >
void	set_session_var (std::string_view var, TYPE const &value, sl loc=sl::current()) &
	Set one of the session variables to a new value. More...
std::string	get_var (std::string_view var, sl loc=sl::current())
	Read currently applicable value of a configuration variable. More...
template<not_borrowed TYPE>
TYPE	get_var_as (std::string_view var, sl loc=sl::current())
	Read currently applicable value of a configuration variable. More...
Password encryption
Use this when setting a new password for the user if password encryption is enabled. Inputs are the SQL name for the user for whom you with to encrypt a password; the plaintext password; and the hash algorithm. The algorithm must be one of "md5", "scram-sha-256" (introduced in PostgreSQL 10), or nullptr. If the pointer is null, this will query the password_encryption setting from the server, and use the default algorithm as defined there. Returns encrypted version of the password, suitable for encrypted PostgreSQL authentication. Thus you can change a user's password with: void setpw(transaction_base &t, string const &user, string const &pw) { t.exec0("ALTER USER " + user + " " "PASSWORD '" + t.conn().encrypt_password(user,pw) + "'"); } When building this against a libpq older than version 10, this will use an older function which only supports md5. In that case, requesting a different algorithm than md5 will result in a feature_not_supported exception.
std::string	encrypt_password (zview user, zview password, zview algorithm)
	Encrypt a password for a given user. More...
PQXX_ZARGS std::string	encrypt_password (char const user[], char const password[], char const *algorithm=nullptr)
	Encrypt a password for a given user. More...

Prepared statements
PostgreSQL supports prepared SQL statements, i.e. statements that you can register under a name you choose, optimized once by the backend, and executed any number of times under the given name. Prepared statement definitions are not sensitive to transaction boundaries. A statement defined inside a transaction will remain defined outside that transaction, even if the transaction itself is subsequently aborted. Once a statement has been prepared, it will only go away if you close the connection or explicitly "unprepare" the statement. Use the pqxx::transaction_base::exec_prepared functions to execute a prepared statement. See Prepared statements for a full discussion. Warning Using prepared statements can save time, but if your statement takes parameters, it may also make your application significantly slower! The reason is that the server works out a plan for executing the query when you prepare it. At that time, of course it does not know the values for the parameters that you will pass. If you execute a query without preparing it, then the server works out the plan on the spot, with full knowledge of the parameter values. A statement's definition can refer to its parameters as $1, $2, etc. The first parameter you pass to the call provides a value for $1, and so on. Here's an example of how to use prepared statements. using namespace pqxx; void foo(connection &c) { c.prepare("findtable", "select * from pg_tables where name=$1"); work tx{c}; result r = tx.exec_prepared("findtable", "mytable"); if (std::empty(r)) throw runtime_error{"mytable not found!"}; }
class	connecting
class	internal::gate::const_connection_largeobject
class	internal::gate::connection_errorhandler
class	internal::gate::connection_transaction
class	internal::gate::connection_stream_from
class	internal::gate::connection_stream_to
class	internal::gate::connection_largeobject
class	internal::gate::connection_notification_receiver
class	internal::gate::connection_pipeline
class	internal::gate::connection_dbtransaction
class	internal::gate::connection_sql_cursor
void	prepare (zview name, zview definition, sl loc=sl::current()) &
	Define a prepared statement. More...
void	prepare (std::string const &name, std::string const &definition, sl loc=sl::current()) &
	Define a prepared statement. More...
PQXX_ZARGS void	prepare (char const name[], char const definition[], sl loc=sl::current()) &
	Define a prepared statement. More...
void	prepare (std::string_view name, std::string_view definition, sl loc=sl::current()) &
	Define a prepared statement. More...
PQXX_ZARGS void	prepare (char const definition[], sl loc=sl::current()) &
	Define a nameless prepared statement. More...
void	prepare (zview definition, sl loc=sl::current()) &
void	unprepare (std::string_view name, sl loc=sl::current())
	Drop prepared statement. More...
std::string	adorn_name (std::string_view)
	Suffix unique number to name to make it unique within session context. More...
PQXX_ZARGS std::string	esc (char const text[], sl loc=sl::current()) const
	Escape string for use as SQL string literal on this connection. More...
std::string_view	esc (std::string_view text, std::span< char > buffer, sl loc=sl::current())
	Escape string for use as SQL string literal, into buffer. More...
std::string	esc (std::string_view text, sl loc=sl::current()) const
	Escape string for use as SQL string literal on this connection. More...
template<binary DATA>
std::string	esc (DATA const &data) const
	Escape binary string for use as SQL string literal on this connection. More...
template<binary DATA>
zview	esc (DATA const &data, std::span< char > buffer, sl loc=sl::current()) const
	Escape binary string for use as SQL string literal, into buffer. More...
std::string	esc_raw (bytes_view) const
	Escape binary string for use as SQL string literal on this connection. More...
template<binary DATA>
std::string	esc_raw (DATA const &data) const
	Escape binary string for use as SQL string literal on this connection. More...
template<binary DATA>
zview	esc_raw (DATA const &data, std::span< char > buffer) const
	Escape binary string for use as SQL string literal, into buffer. More...
bytes	unesc_bin (std::string_view text, sl loc=sl::current()) const
	Unescape binary data, e.g. from a bytea field. More...
std::string	quote_raw (bytes_view) const
	Escape and quote a string of binary data. More...
template<binary DATA>
std::string	quote_raw (DATA const &data) const
	Escape and quote a string of binary data. More...
std::string	quote_name (std::string_view identifier) const
	Escape and quote an SQL identifier for use in a query. More...
std::string	quote_table (std::string_view name) const
	Escape and quote a table name. More...
std::string	quote_table (table_path) const
	Escape and quote a table path. More...
template<pqxx::char_strings STRINGS>
std::string	quote_columns (STRINGS const &columns, sl=sl::current()) const
	Quote and comma-separate a series of column names. More...
template<typename T >
std::string	quote (T const &t, sl=sl::current()) const
	Represent object as SQL string, including quoting & escaping. More...
std::string	esc_like (std::string_view text, char escape_char='\\', sl loc=sl::current()) const
	Escape string for literal LIKE match. More...
void	cancel_query (sl=sl::current())
	Attempt to cancel the ongoing query, if any. More...
void	set_verbosity (error_verbosity verbosity) &noexcept
	Set session verbosity. More...
void	set_notice_handler (std::function< void(zview)> handler)
	Set a notice handler to the connection. More...
std::vector< errorhandler * >	get_errorhandlers () const
std::string	connection_string () const
	Return a connection string encapsulating this connection's options. More...
void	close (sl=sl::current())
	Explicitly close the connection. More...
internal::pq::PGconn *	release_raw_connection () &&
	Release the raw connection without closing it. More...
void	set_variable (std::string_view var, std::string_view value, sl loc=sl::current()) &
	Set session variable, using SQL's SET command. More...
std::string	get_variable (std::string_view, sl loc=sl::current())
	Read session variable, using SQL's SHOW command. More...
static connection	seize_raw_connection (internal::pq::PGconn *raw_conn, sl loc=sl::current())
	Seize control of a raw libpq connection. More...

Notifications and Receivers
This is PostgreSQL-specific extension that goes beyond standard SQL. It's a communications mechanism between clients on a database, akin to a transactional message bus. A notification happens on a channel, identified by a name. You can set a connection to listen for notifications on the channel, using the connection's listen() function. (Internally this will issue a LISTEN SQL command). Any client on the database can send a notification on that channel by executing a NOTIFY SQL command. The transaction classes implement a convenience function for this, called transaction_base::notify(). Notifications can carry an optional payload string. This is free-form text which carries additional information to the receiver. Warning There are a few pitfalls with the channel names: case sensitivity and encodings. They are not too hard to avoid, but the safest thing to do is use only lower-case ASCII names. Case sensitivity Channel names are case-sensitive. By default, however, PostgreSQL does convert the channel name in a NOTIFY or LISTEN command to lower-case, to give the impression that it is not case-sensitive while keeping the performance cost low. Thus, a LISTEN Hello will pick up a notification from NOTIFY Hello but also one from NOTIFY hello, because the database converts Hello into hello going in either direction. You can prevent this conversion by putting the name in double quotes, as quote_name() does. This is what libpqxx's notification functions do. If you use libpqxx to lisen on Hello but raw SQL to notify Hello, the notification will not arrive because the notification actually uses the string hello instead. Confused? Safest thing to do is to use only lower-case letters in the channel names! Transactions Both listening and notifying are transactional in the backend: they only take effect once the back-end transaction in which you do them is committed. For an outgoing notification, this means that the transaction holds on to the outgoing message until you commit. (A nontransaction does not start a backend transaction, so if that's the transaction type you're using, the message does go out immediately.) For listening to incoming notifications, it gets a bit more complicated. To avoid complicating its internal bookkeeping, libpqxx only lets you start listening while no transaction is open. No notifications will come in while you're in a transaction... again unless it's a nontransaction of course, because that does not open a transaction on the backend. Exceptions If your handler throws an exception, that will simply propagate up the call chain to wherever you were when you received it. This is differnt from the old notification_receiver mechanism which logged exceptions but did not propagate them. Encoding When a client sends a notification, it does so in its client encoding. If necessary, the back-end converts them to its internal encoding. And then when a client receives the notification, the database converts it to the receiver's client encoding. Simple enough, right? However if you should change your connection's client encoding after you start listening on a channel, then any notifications you receive may have different channel names than the ones for which you are listening. If this could be a problem in your scenario, stick to names in pure ASCII. Those will look the same in all the encodings postgres supports.
using	notification_handler = std::function< void(notification)>
	A handler callback for incoming notifications on a given channel. More...
int	get_notifs (sl=sl::current())
	Check for pending notifications and take appropriate action. More...
int	await_notification (sl=sl::current())
	Wait briefly for a notification to come in. More...
int	await_notification (std::time_t seconds=10, long microseconds=0, sl=sl::current())
	Wait for a notification to come in, or for given timeout to pass. More...
void	listen (std::string_view channel, notification_handler handler={}, sl=sl::current())
	Attach a handler to a notification channel. More...

Detailed Description

Connection to a database.

This is the first class to look at when you wish to work with a database through libpqxx. As per RAII principles, the connection opens during construction, and closes upon destruction.

To query or manipulate the database once connected, use one of the transaction classes. Their API is defined in pqxx::transaction_base.

When a connection breaks, or fails to establish itself in the first place, you will typically get a broken_connection exception. In some cases when a physical network connection disappears, it can take minutes before this happens, as various layers of software try to reconnect.

Warning

On Unix-like systems, including GNU and BSD systems, your program may receive the SIGPIPE signal when the connection to the backend breaks. By default this signal will abort your program. Use signal(SIGPIPE, SIG_IGN) if you want your program to continue running after a connection fails.

Member Typedef Documentation

notification_handler

using pqxx::connection::notification_handler = std::function<void(notification)>

A handler callback for incoming notifications on a given channel.

Your callback must accept a Notifications and Receivers object. This object can and will exist only for the duration of the handling of that one incoming notification.

The handler can be "empty," i.e. contain no code. Setting an empty handler on a channel disables listening on that channel.

Constructor & Destructor Documentation

connection() [1/6]

pqxx::connection::connection ( sl  loc = sl::current() )

inlineexplicit

connection() [2/6]

template<pqxx::ZString STRING, ZKey_ZValues MAPPING>

pqxx::connection::connection ( STRING const &  connection_string, MAPPING &&  params = empty_params_t(), sl  loc = sl::current()  )

inlineexplicit

Connect to a database with both connection string and parameter pairs.

If a parameter is defined both in connection_string and in params, the value in params takes hold.

If a parameter is defined more than once in params, the last definition takes hold.

connection() [3/6]

template<pqxx::ZString STRING>

pqxx::connection::connection ( STRING const &  connection_string, sl  loc = sl::current()  )

inlineexplicit

Connect to a database, passing a connection string.

If a parameter is defined both in connection_string and in params, the value in params takes hold.

If a parameter is defined more than once in params, the last definition takes hold.

connection() [4/6]

template<ZKey_ZValues MAPPING>

pqxx::connection::connection ( MAPPING &&  params, sl  loc = sl::current()  )

inlineexplicit

Connect to a database, passing connection parameters.

connection() [5/6]

pqxx::connection::connection	(	connection &&	rhs,
		sl	loc = sl::current()
	)

Move constructor.

Moving a connection is not allowed if it has an open transaction, or has error handlers or is listening for notifications. In those situations, other objects may hold references to the old object which would become invalid and might produce hard-to-diagnose bugs.

~connection()

pqxx::connection::~connection ( )

inline

connection() [6/6]

pqxx::connection::connection ( connection const &  )

delete

Member Function Documentation

adorn_name()

std::string pqxx::connection::adorn_name

(

std::string_view

n

)

Suffix unique number to name to make it unique within session context.

Used internally to generate identifiers for SQL objects (such as cursors and nested transactions) based on a given human-readable base name.

await_notification() [1/2]

int pqxx::connection::await_notification

(

sl

loc = sl::current()

)

Wait briefly for a notification to come in.

There are other events that will also cancel the wait, such as the backend failing, or some kinds of signal coming in. After a while the function just returns anyway.

This means that the function can return early, before any notification comes in or the timeout expires. Your code MUST be ready to handle such early returns.

If a notification does come in, this function will immediately process it, along with any other notifications that may have been pending, calling any handlers you may have set for them. It will then return.

To wait for notifications from your own event loop instead, wait until there is incoming data on the connection's socket to be read, then call get_notifs repeatedly until it returns zero. This allows you to handle other events besides notifications with a single wait point.

If your notifcation handler throws an exception, this function will just propagate it on up to you. (This is different from the old notification_receiver mechanism, which would merely log them.)

Returns

Number of notifications processed.

await_notification() [2/2]

int pqxx::connection::await_notification	(	std::time_t	seconds = 10,
		long	microseconds = 0,
		sl	loc = sl::current()
	)

Wait for a notification to come in, or for given timeout to pass.

There are other events that will also cancel the wait, such as the backend failing, or some kinds of signal coming in.

This means that the function can return early, before any notification comes in or the timeout expires. Your code MUST be ready to handle such early returns.

If a notification does come in, this function will immediately process it, along with any other notifications that may have been pending, calling any handlers you may have set for them. It will then return.

To wait for notifications from your own event loop instead, wait until there is incoming data on the connection's socket to be read, then call get_notifs repeatedly until it returns zero. This allows you to handle other events besides notifications with a single wait point.

If your notifcation handler throws an exception, this function will just propagate it on up to you. (This is different from the old notification_receiver mechanism, which would merely log them.)

Returns

Number of notifications processed.

backendpid()

int pqxx::connection::backendpid ( ) const &

noexcept

Process ID for backend process, or 0 if inactive.

cancel_query()

void pqxx::connection::cancel_query

(

sl

loc = sl::current()

)

Attempt to cancel the ongoing query, if any.

You can use this from another thread, and/or while a query is executing in a pipeline, but it's up to you to ensure that you're not canceling the wrong query. This may involve locking.

close()

void pqxx::connection::close

(

sl

= sl::current()

)

Explicitly close the connection.

The destructor will do this for you automatically. Still, there is a reason to close() objects explicitly where possible: if an error should occur while closing, close() can throw an exception. A destructor cannot.

Closing a connection is idempotent. Closing a connection that's already closed does nothing.

connection_string()

std::string pqxx::connection::connection_string

(

)

const

Return a connection string encapsulating this connection's options.

The connection must be currently open for this to work.

Returns a reconstruction of this connection's connection string. It may not exactly match the connection string you passed in when creating this connection.

dbname()

char const * pqxx::connection::dbname ( ) const

noexcept

Name of the database to which we're connected, if any.

Returns nullptr when not connected.

encoding_id()

int pqxx::connection::encoding_id

(

sl

loc = sl::current()

)

const

Get the connection's encoding, as a PostgreSQL-defined code.

encrypt_password() [1/2]

std::string pqxx::connection::encrypt_password	(	char const	user[],
		char const	password[],
		char const *	algorithm = nullptr
	)

Encrypt a password for a given user.

encrypt_password() [2/2]

std::string pqxx::connection::encrypt_password ( zview  user, zview  password, zview  algorithm  )

inline

Encrypt a password for a given user.

esc() [1/5]

PQXX_ZARGS std::string pqxx::connection::esc ( char const  text[], sl  loc = sl::current()  ) const

inline

Escape string for use as SQL string literal on this connection.

esc() [2/5]

template<binary DATA>

std::string pqxx::connection::esc ( DATA const &  data ) const

inline

Escape binary string for use as SQL string literal on this connection.

This is identical to esc_raw(data).

esc() [3/5]

template<binary DATA>

zview pqxx::connection::esc ( DATA const &  data, std::span< char >  buffer, sl  loc = sl::current()  ) const

inline

Escape binary string for use as SQL string literal, into buffer.

Use this variant when you want to re-use the same buffer across multiple calls. If that's not the case, or convenience and simplicity are more important, use the single-argument variant.

For every byte in data, there must be at least two bytes of space in buffer; plus there must be two bytes of space for a header and one for a trailing zero. Throws range_error if this space is not available.

Returns a reference to the escaped string, which is actually stored in buffer.

esc() [4/5]

std::string pqxx::connection::esc	(	std::string_view	text,
		sl	loc = sl::current()
	)		const

Escape string for use as SQL string literal on this connection.

Warning

This is meant for text strings only. It cannot contain bytes whose value is zero ("nul bytes").

esc() [5/5]

std::string_view pqxx::connection::esc ( std::string_view  text, std::span< char >  buffer, sl  loc = sl::current()  )

inline

Escape string for use as SQL string literal, into buffer.

Use this variant when you want to re-use the same buffer across multiple calls. If that's not the case, or convenience and simplicity are more important, use the single-argument variant.

For every byte in text, there must be at least 2 bytes of space in buffer; plus there must be one byte of space for a trailing zero. Throws range_error if this space is not available.

Returns a reference to the escaped string, which is actually stored in buffer.

esc_like()

std::string pqxx::connection::esc_like	(	std::string_view	text,
		char	escape_char = '\\',
		sl	loc = sl::current()
	)		const

Escape string for literal LIKE match.

Use this when part of an SQL "LIKE" pattern should match only as a literal string, not as a pattern, even if it contains "%" or "_" characters that would normally act as wildcards.

The string does not get string-escaped or quoted. You do that later.

For instance, let's say you have a string name entered by the user, and you're searching a file column for items that match name followed by a dot and three letters. Even if name contains wildcard characters "%" or "_", you only want those to match literally, so "_" only matches "_" and "%" only matches a single "%".

You do that by "like-escaping" name, appending the wildcard pattern ".___", and finally, escaping and quoting the result for inclusion in your query:

tx.exec(
    "SELECT file FROM item WHERE file LIKE " +
    tx.quote(tx.esc_like(name) + ".___"));

The SQL "LIKE" operator also lets you choose your own escape character. This is supported, but must be a single-byte character.

esc_raw() [1/3]

std::string pqxx::connection::esc_raw

(

bytes_view

bin

)

const

Escape binary string for use as SQL string literal on this connection.

You can also just use esc with a binary string.

esc_raw() [2/3]

template<binary DATA>

std::string pqxx::connection::esc_raw ( DATA const &  data ) const

inline

Escape binary string for use as SQL string literal on this connection.

You can also just use esc with a binary string.

esc_raw() [3/3]

template<binary DATA>

zview pqxx::connection::esc_raw ( DATA const &  data, std::span< char >  buffer  ) const

inline

Escape binary string for use as SQL string literal, into buffer.

get_client_encoding()

std::string pqxx::connection::get_client_encoding

(

sl

loc = sl::current()

)

const

Get client-side character encoding, by name.

Each connection is governed by a "client encoding," which dictates how strings and other text is represented in bytes. The database server will send text data to you in this encoding, and you should use it for the queries and data which you send to the server.

Search the PostgreSQL documentation for "character set encodings" to find out more about the available encodings, how to extend them, and how to use them. Not all server-side encodings are compatible with all client-side encodings or vice versa.

Encoding names are case-insensitive, so e.g. "UTF8" is equivalent to "utf8".

You can change the client encoding, but this may not work when the connection is in a special state, such as when streaming a table. It's not clear what happens if you change the encoding during a transaction, and then abort the transaction.

get_encoding_group()

encoding_group pqxx::connection::get_encoding_group ( sl  loc = sl::current() ) const

inline

Read the curent client encoding's pqxx::encoding_group.

get_errorhandlers()

std::vector< pqxx::errorhandler * > pqxx::connection::get_errorhandlers

(

)

const

Deprecated:

Return pointers to the active errorhandlers.

The entries are ordered from oldest to newest handler.

The pointers point to the real errorhandlers. The container it returns however is a copy of the one internal to the connection, not a reference.

get_notifs()

int pqxx::connection::get_notifs

(

sl

loc = sl::current()

)

Check for pending notifications and take appropriate action.

This does not block. To wait for incoming notifications, either call await_notification() (it calls this function); or wait for incoming data on the connection's socket (i.e. wait to read), and then call this function repeatedly until it returns zero. After that, there are no more pending notifications so you may want to wait again, or move on and do other work.

If any notifications are pending when you call this function, it processes them by checking for a matching notification handler, and if it finds one, invoking it. If there is no matching handler, nothing happens.

If your notifcation handler throws an exception, get_notifs() will just propagate it back to you. (This is different from the old notification_receiver mechanism, which would merely log them.)

Returns

Number of notifications processed.

get_var()

std::string pqxx::connection::get_var	(	std::string_view	var,
		sl	loc = sl::current()
	)

Read currently applicable value of a configuration variable.

This function executes an SQL statement, so it won't work while a pipeline, query stream, or other object derived from transaction_focus is active on the connection.

Returns

The variable's current string value (which may be empty).

get_var_as()

template<not_borrowed TYPE>

TYPE pqxx::connection::get_var_as ( std::string_view  var, sl  loc = sl::current()  )

inline

Read currently applicable value of a configuration variable.

This function executes an SQL statement, so it won't work while a pipeline, query stream, or other object derived from transaction_focus is active on the connection.

Warning

The connection does not store the underlying string anywhere. So if you try to read the variable as a std::string_view, a std::span, a pqxx::zview, or anything like that... the string value will no longer be valid by the time you receive it! If you want to read the variable as a string value, use std::string.

get_variable()

std::string pqxx::connection::get_variable	(	std::string_view	var,
		sl	loc = sl::current()
	)

Read session variable, using SQL's SHOW command.

Warning

This executes an SQL query, so do not get or set variables while a table stream or pipeline is active on the same connection.

hostname()

char const * pqxx::connection::hostname ( ) const

noexcept

Database server address, if given.

This may be an IP address, or a hostname, or (for a Unix domain socket) a socket path. Returns nullptr when not connected.

is_open()

bool pqxx::connection::is_open ( ) const

noexcept

Is this connection open at the moment?

Warning

Most code does not need this function. Resist the temptation to check your connection after opening it: if the connection attempt failed, the constructor will never even return, throwing a broken_connection exception instead.

listen()

void pqxx::connection::listen	(	std::string_view	channel,
		notification_handler	handler = {},
		sl	loc = sl::current()
	)

Attach a handler to a notification channel.

Issues a LISTEN SQL command for channel channel, and stores handler as the callback for when a notification comes in on that channel.

The connection can call this handler when you call get_notifs() or await_notification() on the connection. Some internal functions may also call these functions. The client-side handling is fully synchronous and notifications only come in while the connection is not in a back-end transaction.

The handler is a std::function (see notification_handler), but you can simply pass in a lambda with the right parameters, or a function, or an object of a type you define that happens to implemnt the right function call operator.

Your handler probably needs to interact with your application's data; the simple way to get that working is to pass a lambda with a closure referencing the data items you need.

If the handler is empty (the default), then that stops the connection listening on the channel. It cancels your subscription, so to speak. You can do that as many times as you like, even when you never started listening to that channel in the first place.

A connection can only have one handler per channel, so if you register two different handlers on the same channel, then the second overwrites the first.

operator=() [1/2]

pqxx::connection & pqxx::connection::operator=

(

connection &&

rhs

)

Move assignment.

Neither connection can have an open transaction, errorhandler, or notification_receiver.

If libpqxx needs to throw an exception during this operation, its error message will state the std::source_location not for where you call it, since there is no way to pass a std::source_location parameter in the assignment operator. Instead, it will report the location where the current connection was created.

operator=() [2/2]

connection& pqxx::connection::operator= ( connection const &  )

delete

port()

char const * pqxx::connection::port ( ) const

noexcept

Server port number on which we are connected to the database.

port_number()

std::optional< int > pqxx::connection::port_number

(

sl

loc = sl::current()

)

const

Server port number on which we are connected to the database, if any.

prepare() [1/6]

void pqxx::connection::prepare	(	char const	definition[],
		sl	loc = sl::current()
	)		&

Define a nameless prepared statement.

prepare() [2/6]

void pqxx::connection::prepare	(	char const	name[],
		char const	definition[],
		sl	loc = sl::current()
	)		&

Define a prepared statement.

Parameters

name	unique name for the new prepared statement.
definition	SQL statement to prepare.

prepare() [3/6]

void pqxx::connection::prepare ( std::string const &  name, std::string const &  definition, sl  loc = sl::current()  ) &

inline

Define a prepared statement.

Extra overload for disambiguation. It may also help avoid the slightly less efficient string_view-based overload.

Parameters

name	unique name for the new prepared statement.
definition	SQL statement to prepare.

prepare() [4/6]

void pqxx::connection::prepare ( std::string_view  name, std::string_view  definition, sl  loc = sl::current()  ) &

inline

Define a prepared statement.

This is a convenience overload, slightly less efficient than the versions that take std::string, pqxx::zview or raw C strings. The reason is that these functions internally call a C-level function that expects zero-terminated strings.

If you cannot guarantee that these strings are zero-terminated, the function will have to create temporary internal copies of these strings in order to ensure the terminating zero.

Parameters

name	unique name for the new prepared statement.
definition	SQL statement to prepare.

prepare() [5/6]

void pqxx::connection::prepare ( zview  definition, sl  loc = sl::current()  ) &

inline

prepare() [6/6]

void pqxx::connection::prepare ( zview  name, zview  definition, sl  loc = sl::current()  ) &

inline

Define a prepared statement.

Parameters

name	unique name for the new prepared statement.
definition	SQL statement to prepare.

process_notice() [1/2]

void pqxx::connection::process_notice ( char const  msg[] )

noexcept

Invoke notice processor function. The message should end in newline.

process_notice() [2/2]

void pqxx::connection::process_notice ( zview  msg )

noexcept

Invoke notice processor function. Newline at end is recommended.

The zview variant, with a message ending in newline, is the most efficient way to call process_notice.

protocol_version()

int pqxx::connection::protocol_version ( ) const

noexcept

What version of the PostgreSQL protocol is this connection using?

The answer can be 0 (when there is no connection); 3 for protocol 3.0; or possibly higher values as newer protocol versions come into use.

quote()

template<typename T >

std::string pqxx::connection::quote ( T const &  t, sl  loc = sl::current()  ) const

inline

Represent object as SQL string, including quoting & escaping.

Recognises nulls and represents them as SQL nulls. They get no quotes.

quote_columns()

template<pqxx::char_strings STRINGS>

std::string pqxx::connection::quote_columns ( STRINGS const &  columns, sl  loc = sl::current()  ) const

inline

Quote and comma-separate a series of column names.

Use this to save a bit of work in cases where you repeatedly need to pass the same list of column names, e.g. with stream_to and stream_from. Some functions that need to quote the columns list internally, will have a "raw" alternative which let you do the quoting yourself. It's a bit of extra work, but it can in rare cases let you eliminate some duplicate work in quoting them repeatedly.

quote_name()

std::string pqxx::connection::quote_name

(

std::string_view

identifier

)

const

Escape and quote an SQL identifier for use in a query.

quote_raw() [1/2]

std::string pqxx::connection::quote_raw

(

bytes_view

bytes

)

const

Escape and quote a string of binary data.

You can also just use quote with binary data.

quote_raw() [2/2]

template<binary DATA>

std::string pqxx::connection::quote_raw ( DATA const &  data ) const

inline

Escape and quote a string of binary data.

You can also just use quote with binary data.

quote_table() [1/2]

std::string pqxx::connection::quote_table

(

std::string_view

name

)

const

Escape and quote a table name.

When passing just a table name, this is just another name for quote_name.

quote_table() [2/2]

std::string pqxx::connection::quote_table

(

table_path

path

)

const

Escape and quote a table path.

A table path consists of a table name, optionally prefixed by a schema name; and if both are given, they are in turn optionally prefixed by a database name.

Each portion of the path (database name, schema name, table name) will be quoted separately, and they will be joined together by dots. So for example, myschema.mytable will become "myschema"."mytable".

release_raw_connection()

internal::pq::PGconn* pqxx::connection::release_raw_connection ( ) &&

inline

Release the raw connection without closing it.

Warning

Do not do this. It's for very rare, very specific use-cases. The mechanism may change (or break) in unexpected ways in future versions.

The connection object becomes unusable after this.

In order to use the resulting pointer, for most purposes you'll have to cast it to its original C type: ::PGconn * as defined by libpq.

seize_raw_connection()

static connection pqxx::connection::seize_raw_connection ( internal::pq::PGconn *  raw_conn, sl  loc = sl::current()  )

inlinestatic

Seize control of a raw libpq connection.

Warning

Do not do this. Please. It's for very rare, very specific use-cases. The mechanism may change (or break) in unexpected ways in future versions.

Parameters

raw_conn

a raw libpq ::PQconn pointer, cast to a pqxx::internal::pq::PGconn pointer.

server_version()

int pqxx::connection::server_version ( ) const

noexcept

What version of the PostgreSQL server are we connected to?

The result is a bit complicated: each of the major, medium, and minor release numbers is written as a two-digit decimal number, and the three are then concatenated. Thus server version 9.4.2 will be returned as the decimal number 90402. If there is no connection to the server, this returns zero.

Warning

When writing version numbers in your code, don't add zero at the beginning! Numbers beginning with zero are interpreted as octal (base-8) in C++. Thus, 070402 is not the same as 70402, and 080000 is not a number at all because there is no digit "8" in octal notation. Use strictly decimal notation when it comes to these version numbers.

set_client_encoding() [1/2]

void pqxx::connection::set_client_encoding	(	char const	encoding[],
		sl	loc = sl::current()
	)		&

Set client-side character encoding, by name.

Parameters

encoding

Name of the character set encoding to use.

set_client_encoding() [2/2]

void pqxx::connection::set_client_encoding ( zview  encoding, sl  loc = sl::current()  ) &

inline

Set client-side character encoding, by name.

Parameters

encoding

Name of the character set encoding to use.

set_notice_handler()

void pqxx::connection::set_notice_handler ( std::function< void(zview)>  handler )

inline

Set a notice handler to the connection.

When a notice comes in (a warning or error message), the connection or result object on which it happens will call the notice handler, passing the message as its argument.

The handler must not throw any exceptions. If it does, the program will terminate.

Warning

It's not just the connection that can call a notice handler, but any of the result objects that it produces as well. So, be prepared for the possibility that the handler may still receive a call after the connection has been closed.

set_session_var()

template<typename TYPE >

void pqxx::connection::set_session_var ( std::string_view  var, TYPE const &  value, sl  loc = sl::current()  ) &

inline

Set one of the session variables to a new value.

This executes SQL, so do not do it while a pipeline or stream is active on the connection.

The value you set here will last for the rest of the connection's duration, or until you set a new value.

If you set the value while in a dbtransaction (i.e. any transaction that is not a nontransaction), then rolling back the transaction will undo the change.

All applies to setting session variables. You can also set the same variables as local variables, in which case they will always revert to their previous value when the transaction ends (or when you overwrite them of course). To set a local variable, simply execute an SQL statement along the lines of "`SET LOCAL var = 'value'`" inside your transaction.

Parameters

var	The variable to set.
value	The new value for the variable.

Exceptions

set_variable()

void pqxx::connection::set_variable	(	std::string_view	var,
		std::string_view	value,
		sl	loc = sl::current()
	)		&

Set session variable, using SQL's SET command.

Deprecated:

To set a session variable, use set_session_var. To set a transaction-local variable, execute an SQL SET command.

Warning

When setting a string value, you must escape and quote it first. Use the quote() function to do that.

This executes an SQL query, so do not get or set variables while a table stream or pipeline is active on the same connection.

Parameters

var	Variable to set.
value	New value for Var. This can be any SQL expression. If it's a string, be sure that it's properly escaped and quoted.

set_verbosity()

void pqxx::connection::set_verbosity ( error_verbosity  verbosity ) &

noexcept

Set session verbosity.

Set the verbosity of error messages to "terse", "normal" (the default), or "verbose."

This affects the notices that the connection and its result objects will pass to your notice handler.

If "terse", returned messages include severity, primary text, and position only; this will normally fit on a single line. "normal" produces messages that include the above plus any detail, hint, or context fields (these might span multiple lines). "verbose" includes all available fields.

sock()

int pqxx::connection::sock ( ) const &

noexcept

Socket currently used for connection, or -1 for none.

Query the current socket number. This is intended for event loops based on functions such as select() or poll(), where you're waiting for any of multiple file descriptors to become ready for communication.

Please try to stay away from this function. It is really only meant for event loops that need to wait on more than one file descriptor. If all you need is to block until a notification arrives, for instance, use await_notification(). If you want to issue queries and retrieve results in nonblocking fashion, check out the pipeline class.

trace()

void pqxx::connection::trace ( std::FILE *  )

noexcept

Enable tracing to a given output stream, or nullptr to disable.

unesc_bin()

bytes pqxx::connection::unesc_bin ( std::string_view  text, sl  loc = sl::current()  ) const

inline

Unescape binary data, e.g. from a bytea field.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

(The data must be encoded in PostgreSQL's "hex" format. The legacy "bytea" escape format, used prior to PostgreSQL 9.0, is no longer supported.)

unprepare()

void pqxx::connection::unprepare	(	std::string_view	name,
		sl	loc = sl::current()
	)

Drop prepared statement.

username()

char const * pqxx::connection::username ( ) const

noexcept

Database user ID under which we are connected, if any.

Returns nullptr when not connected.

Friends And Related Function Documentation

connecting

friend class connecting

friend

internal::gate::connection_dbtransaction

friend class internal::gate::connection_dbtransaction

friend

internal::gate::connection_errorhandler

friend class internal::gate::connection_errorhandler

friend

internal::gate::connection_largeobject

friend class internal::gate::connection_largeobject

friend

internal::gate::connection_notification_receiver

friend class internal::gate::connection_notification_receiver

friend

internal::gate::connection_pipeline

friend class internal::gate::connection_pipeline

friend

internal::gate::connection_sql_cursor

friend class internal::gate::connection_sql_cursor

friend

internal::gate::connection_stream_from

friend class internal::gate::connection_stream_from

friend

internal::gate::connection_stream_to

friend class internal::gate::connection_stream_to

friend

internal::gate::connection_transaction

friend class internal::gate::connection_transaction

friend

internal::gate::const_connection_largeobject

friend class internal::gate::const_connection_largeobject

friend

---

The documentation for this class was generated from the following files:

• include/pqxx/connection.hxx
• src/connection.cxx