13#ifndef PQXX_H_CONNECTION
14#define PQXX_H_CONNECTION
16#if !defined(PQXX_HEADER_PRE)
17# error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
22#include <initializer_list>
30#if defined(PQXX_HAVE_CONCEPTS) && __has_include(<ranges>)
34#include "pqxx/errorhandler.hxx"
35#include "pqxx/except.hxx"
36#include "pqxx/internal/concat.hxx"
37#include "pqxx/params.hxx"
38#include "pqxx/separated_list.hxx"
39#include "pqxx/strconv.hxx"
40#include "pqxx/types.hxx"
41#include "pqxx/util.hxx"
42#include "pqxx/zview.hxx"
82#if defined(PQXX_HAVE_CONCEPTS)
85concept ZKey_ZValues = std::ranges::input_range<T> and
requires(T t) {
87 { std::get<0>(*std::cbegin(t)) } -> ZString;
88 { std::get<1>(*std::cbegin(t)) } -> ZString;
89} and std::tuple_size_v<typename std::ranges::iterator_t<T>::value_type> == 2;
105namespace pqxx::internal::gate
107class connection_dbtransaction;
108class connection_errorhandler;
109class connection_largeobject;
110class connection_notification_receiver;
111class connection_pipeline;
112class connection_sql_cursor;
113struct connection_stream_from;
114class connection_stream_to;
115class connection_transaction;
116class const_connection_largeobject;
255#if defined(PQXX_HAVE_CONCEPTS)
272 template<
internal::ZKey_ZValues MAPPING>
282 catch (std::exception
const &)
290 connection &operator=(connection &&rhs);
292 connection(connection
const &) =
delete;
293 connection &operator=(connection
const &) =
delete;
301 [[nodiscard]]
bool PQXX_PURE is_open() const noexcept;
304 void process_notice(
char const[]) noexcept;
309 void process_notice(zview) noexcept;
312 void trace(std::FILE *) noexcept;
326 [[nodiscard]]
char const *dbname() const;
330 [[nodiscard]]
char const *username() const;
336 [[nodiscard]]
char const *hostname() const;
339 [[nodiscard]]
char const *port() const;
342 [[nodiscard]]
int PQXX_PURE backendpid() const & noexcept;
355 [[nodiscard]]
int PQXX_PURE sock() const & noexcept;
361 [[nodiscard]]
int PQXX_PURE protocol_version() const noexcept;
376 [[nodiscard]]
int PQXX_PURE server_version() const noexcept;
401 [[nodiscard]] std::
string get_client_encoding() const;
407 void set_client_encoding(
zview encoding) &
409 set_client_encoding(encoding.c_str());
416 void set_client_encoding(
char const encoding[]) &;
419 [[nodiscard]]
int encoding_id()
const;
445 template<
typename TYPE>
464 std::string get_var(std::string_view var);
473 template<
typename TYPE> TYPE
get_var_as(std::string_view var)
475 return from_string<TYPE>(get_var(var));
515 int await_notification();
530 int await_notification(std::time_t seconds,
long microseconds);
564 [[nodiscard]] std::string
571 char const user[],
char const password[],
char const *algorithm =
nullptr);
624 prepare(name.c_str(), definition.c_str());
631 void prepare(
char const name[],
char const definition[]) &;
641 void prepare(
char const definition[]) &;
642 void prepare(
zview definition) & {
return prepare(definition.c_str()); }
645 void unprepare(std::string_view name);
654 [[nodiscard]] std::string adorn_name(std::string_view);
662 [[nodiscard]] std::string
esc(
char const text[])
const
664 return esc(std::string_view{text});
667#if defined(PQXX_HAVE_SPAN)
680 [[nodiscard]] std::string_view
681 esc(std::string_view text, std::span<char> buffer)
683 auto const size{std::size(text)}, space{std::size(buffer)};
684 auto const needed{2 * size + 1};
687 "Not enough room to escape string of ", size,
" byte(s): need ",
688 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
689 auto const data{buffer.data()};
690 return {data, esc_to_buf(text, data)};
698 [[nodiscard]] std::string esc(std::string_view text)
const;
700#if defined(PQXX_HAVE_CONCEPTS)
703 template<binary DATA> [[nodiscard]] std::string esc(DATA
const &data)
const
705 return esc_raw(data);
709#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
722 template<binary DATA>
723 [[nodiscard]] zview esc(DATA
const &data, std::span<char> buffer)
const
725 auto const size{std::size(data)}, space{std::size(buffer)};
729 "Not enough room to escape binary string of ", size,
" byte(s): need ",
730 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
732 bytes_view view{std::data(data), std::size(data)};
733 auto const out{std::data(buffer)};
737 return zview{out, needed - 1};
742 [[deprecated(
"Use std::byte for binary data.")]] std::string
743 esc_raw(
unsigned char const bin[], std::size_t len)
const;
747 [[nodiscard]] std::string esc_raw(
bytes_view)
const;
749#if defined(PQXX_HAVE_SPAN)
752 [[nodiscard]] std::string esc_raw(
bytes_view, std::span<char> buffer)
const;
755#if defined(PQXX_HAVE_CONCEPTS)
758 template<binary DATA>
759 [[nodiscard]] std::string esc_raw(DATA
const &data)
const
761 return esc_raw(
bytes_view{std::data(data), std::size(data)});
765#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
767 template<binary DATA>
768 [[nodiscard]] zview esc_raw(DATA
const &data, std::span<char> buffer)
const
794#if defined(PQXX_HAVE_CONCEPTS)
797 template<binary DATA>
798 [[nodiscard]] std::string quote_raw(DATA
const &data)
const
800 return quote_raw(
bytes_view{std::data(data), std::size(data)});
806 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
813 [[nodiscard]] std::string quote_table(std::string_view name)
const;
825 [[nodiscard]] std::string quote_table(
table_path)
const;
836 template<PQXX_CHAR_STRINGS_ARG STRINGS>
837 inline std::string quote_columns(STRINGS
const &columns)
const;
845 [[nodiscard]]
inline std::string quote(T
const &t)
const;
847 [[deprecated(
"Use std::byte for binary data.")]] std::string
848 quote(binarystring
const &)
const;
881 [[nodiscard]] std::string
882 esc_like(std::string_view text,
char escape_char =
'\\')
const;
889 [[deprecated(
"Use std::string_view or pqxx:zview.")]] std::string
890 esc(
char const text[], std::size_t maxlen)
const
892 return esc(std::string_view{text, maxlen});
899 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
902#include "pqxx/internal/ignore-deprecated-pre.hxx"
903 return unesc_raw(text.c_str());
904#include "pqxx/internal/ignore-deprecated-post.hxx"
911 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
912 unesc_raw(
char const text[])
const;
915 [[deprecated(
"Use quote(bytes_view).")]] std::string
916 quote_raw(
unsigned char const bin[], std::size_t len)
const;
926#if defined(_WIN32) || __has_include(<fcntl.h>)
932 void set_blocking(
bool block) &;
960 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
969 [[nodiscard]] std::string connection_string()
const;
1002 return std::exchange(m_conn,
nullptr);
1019 [[deprecated(
"To set session variables, use set_session_var.")]]
void
1020 set_variable(std::string_view var, std::string_view value) &;
1026 [[deprecated(
"Use get_var instead.")]] std::string
1027 get_variable(std::string_view);
1035 connection(connect_mode, zview connection_string);
1038 explicit connection(internal::pq::PGconn *raw_conn) : m_conn{raw_conn} {}
1046 std::pair<bool, bool> poll_connect();
1049 void init(
char const options[]);
1051 void init(
char const *params[],
char const *values[]);
1052 void complete_init();
1055 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query,
1056 std::string_view desc =
""sv);
1058 void PQXX_PRIVATE set_up_state();
1060 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
1067 std::
size_t esc_to_buf(std::string_view text,
char *buf) const;
1069 friend class internal::gate::const_connection_largeobject;
1070 char const *PQXX_PURE err_msg() const noexcept;
1072 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
1074 result exec_prepared(std::string_view statement, internal::c_params const &);
1077 void check_movable() const;
1079 void check_overwritable() const;
1081 friend class internal::gate::connection_errorhandler;
1082 void PQXX_PRIVATE register_errorhandler(errorhandler *);
1083 void PQXX_PRIVATE unregister_errorhandler(errorhandler *) noexcept;
1085 friend class internal::gate::connection_transaction;
1086 result exec(std::string_view, std::string_view = ""sv);
1088 exec(std::shared_ptr<std::
string> const &, std::string_view = ""sv);
1089 void PQXX_PRIVATE register_transaction(transaction_base *);
1090 void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;
1092 friend struct internal::gate::connection_stream_from;
1099 std::pair<std::unique_ptr<
char,
void (*)(
void const *)>, std::
size_t>
1102 friend class internal::gate::connection_stream_to;
1103 void PQXX_PRIVATE write_copy_line(std::string_view);
1104 void PQXX_PRIVATE end_copy_write();
1106 friend class internal::gate::connection_largeobject;
1107 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
1109 friend class internal::gate::connection_notification_receiver;
1110 void add_receiver(notification_receiver *);
1111 void remove_receiver(notification_receiver *)
noexcept;
1113 friend class internal::gate::connection_pipeline;
1114 void PQXX_PRIVATE start_exec(
char const query[]);
1115 bool PQXX_PRIVATE consume_input() noexcept;
1116 bool PQXX_PRIVATE is_busy() const noexcept;
1117 internal::pq::PGresult *get_result();
1119 friend class internal::gate::connection_dbtransaction;
1120 friend class internal::gate::connection_sql_cursor;
1122 result exec_params(std::string_view query, internal::c_params const &args);
1125 internal::pq::PGconn *m_conn =
nullptr;
1135 transaction_base const *m_trans =
nullptr;
1137 std::list<errorhandler *> m_errorhandlers;
1139 using receiver_list =
1140 std::multimap<std::
string,
pqxx::notification_receiver *>;
1142 receiver_list m_receivers;
1145 int m_unique_id = 0;
1209 [[nodiscard]]
int sock() const & noexcept {
return m_conn.sock(); }
1227 [[nodiscard]]
constexpr bool done() const & noexcept
1229 return not m_reading and not m_writing;
1245 bool m_reading{
false};
1246 bool m_writing{
true};
1266 std::string buf{
'\''};
1267 buf.resize(2 + 2 * std::size(text) + 1);
1268 auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
1269 auto const closing_quote{1 + content_bytes};
1270 buf[closing_quote] =
'\'';
1271 auto const end{closing_quote + 1};
1278template<PQXX_CHAR_STRINGS_ARG STRINGS>
1282 ","sv, std::cbegin(columns), std::cend(columns),
1283 [
this](
auto col) {
return this->quote_name(*col); });
1287#if defined(PQXX_HAVE_CONCEPTS)
1288template<
internal::ZKey_ZValues MAPPING>
1289inline connection::connection(MAPPING
const &
params)
1293 std::vector<char const *> keys, values;
1294 if constexpr (std::ranges::sized_range<MAPPING>)
1296 auto const size{std::ranges::size(
params) + 1};
1298 values.reserve(size);
1300 for (
auto const &[key, value] : params)
1305 keys.push_back(
nullptr);
1306 values.push_back(
nullptr);
1307 init(std::data(keys), std::data(values));
1314 deprecated(
"Use connection::encrypt_password instead.")]] std::string
1320 deprecated(
"Use connection::encrypt_password instead.")]]
inline std::string
1323#include "pqxx/internal/ignore-deprecated-pre.hxx"
1325#include "pqxx/internal/ignore-deprecated-post.hxx"
An ongoing, non-blocking stepping stone to a connection.
Definition: connection.hxx:1198
int sock() const &noexcept
Get the socket. The socket may change during the connection process.
Definition: connection.hxx:1209
constexpr bool done() const &noexcept
Is our connection finished?
Definition: connection.hxx:1227
constexpr bool wait_to_write() const &noexcept
Should we currently wait to be able to write to the socket?
Definition: connection.hxx:1218
void process() &
Progress towards completion (but don't block).
constexpr bool wait_to_read() const &noexcept
Should we currently wait to be able to read from the socket?
Definition: connection.hxx:1212
connecting(zview connection_string=""_zv)
Start connecting.
connection produce() &&
Produce the completed connection object.
Connection to a database.
Definition: connection.hxx:230
std::string encrypt_password(zview user, zview password, zview algorithm)
Encrypt a password for a given user.
Definition: connection.hxx:565
connection(char const options[])
Connect to a database, using options string.
Definition: connection.hxx:235
TYPE get_var_as(std::string_view var)
Read currently applicable value of a variable.
Definition: connection.hxx:473
bytes unesc_bin(std::string_view text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:783
std::string quote_columns(STRINGS const &columns) const
Quote and comma-separate a series of column names.
Definition: connection.hxx:1279
connection(zview options)
Connect to a database, using options string.
Definition: connection.hxx:242
internal::pq::PGconn * release_raw_connection() &&
Release the raw connection without closing it.
Definition: connection.hxx:1000
static connection seize_raw_connection(internal::pq::PGconn *raw_conn)
Seize control of a raw libpq connection.
Definition: connection.hxx:989
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:662
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:900
std::string esc(char const text[], std::size_t maxlen) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:890
void prepare(zview name, zview definition) &
Define a prepared statement.
Definition: connection.hxx:622
void set_session_var(std::string_view var, TYPE const &value) &
Set one of the session variables to a new value.
Definition: connection.hxx:446
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition: connection.hxx:1250
Build a parameter list for a parameterised or prepared statement.
Definition: params.hxx:46
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:38
constexpr char const * c_str() const &noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:96
The caller attempted to set a variable to null, which is not allowed.
Definition: except.hxx:116
Internal items for libpqxx' own use. Do not use these yourself.
Definition: encodings.cxx:33
void PQXX_LIBEXPORT unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:165
std::string concat(TYPE... item)
Efficiently combine a bunch of items into one big string.
Definition: concat.hxx:31
constexpr std::size_t size_esc_bin(std::size_t binary_bytes) noexcept
Compute buffer size needed to escape binary data for use as a BYTEA.
Definition: util.hxx:516
void PQXX_COLD PQXX_LIBEXPORT skip_init_ssl(int skips) noexcept
Control OpenSSL/crypto library initialisation.
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition: zview.hxx:145
void PQXX_LIBEXPORT esc_bin(bytes_view binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:133
constexpr std::size_t size_unesc_bin(std::size_t escaped_bytes) noexcept
Compute binary size from the size of its escaped version.
Definition: util.hxx:525
The home of all libpqxx classes, functions, templates, etc.
Definition: array.cxx:27
std::string separated_list(std::string_view sep, ITER begin, ITER end, ACCESS access)
Represent sequence of values as a string, joined by a given separator.
Definition: separated_list.hxx:46
PQXX_PRIVATE void check_version() noexcept
Definition: util.hxx:236
void skip_init_ssl() noexcept
Control initialisation of OpenSSL and libcrypto libraries.
Definition: connection.hxx:167
bytes_view binary_cast(TYPE const &data)
Cast binary data to a type that libpqxx will recognise as binary.
Definition: util.hxx:409
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition: connection.hxx:182
constexpr bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:514
std::string PQXX_LIBEXPORT encrypt_password(char const user[], char const password[])
Encrypt a password.
std::conditional< has_generic_bytes_char_traits, std::basic_string< std::byte >, std::basic_string< std::byte, byte_char_traits > >::type bytes
Type alias for a container containing bytes.
Definition: util.hxx:375
PQXX_LIBEXPORT std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:566
skip_init
Flags for skipping initialisation of SSL-related libraries.
Definition: connection.hxx:131
@ crypto
Skip initialisation of libcrypto.
Definition: connection.hxx:139
@ openssl
Skip initialisation of OpenSSL library.
Definition: connection.hxx:136
@ nothing
A do-nothing flag that does not affect anything.
Definition: connection.hxx:133
std::conditional< has_generic_bytes_char_traits, std::basic_string_view< std::byte >, std::basic_string_view< std::byte, byte_char_traits > >::type bytes_view
Type alias for a view of bytes.
Definition: util.hxx:385
error_verbosity
Error verbosity levels.
Definition: connection.hxx:187
Traits describing a type's "null value," if any.
Definition: strconv.hxx:91