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>
26 #include <string_view>
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"
79 #if defined(PQXX_HAVE_CONCEPTS)
82 concept ZKey_ZValues =
83 std::ranges::input_range<T> and
89 std::get<0>(*std::cbegin(t))
92 std::get<1>(*std::cbegin(t))
95 std::tuple_size_v<typename std::ranges::iterator_t<T>::value_type> == 2;
96 #endif // PQXX_HAVE_CONCEPTS
107 void PQXX_COLD PQXX_LIBEXPORT
skip_init_ssl(
int flags) noexcept;
113 class connection_dbtransaction;
114 class connection_errorhandler;
115 class connection_largeobject;
116 class connection_notification_receiver;
117 class connection_pipeline;
118 class connection_sql_cursor;
119 struct connection_stream_from;
120 class connection_stream_to;
121 class connection_transaction;
122 class const_connection_largeobject;
193 deprecated(
"Use connection::encrypt_password instead.")]] std::string
199 deprecated(
"Use connection::encrypt_password instead.")]]
inline std::string
202 #include "pqxx/internal/ignore-deprecated-pre.hxx"
204 #include "pqxx/internal/ignore-deprecated-post.hxx"
276 connection(connection &&rhs);
278 #if defined(PQXX_HAVE_CONCEPTS)
295 template<
internal::ZKey_ZValues MAPPING>
296 inline connection(MAPPING
const ¶ms);
297 #endif // PQXX_HAVE_CONCEPTS
305 catch (std::exception
const &)
324 [[nodiscard]]
bool PQXX_PURE is_open() const noexcept;
327 void process_notice(
char const[]) noexcept;
332 void process_notice(
zview) noexcept;
335 void trace(
std::FILE *) noexcept;
349 [[nodiscard]]
char const *dbname() const;
353 [[nodiscard]]
char const *username() const;
359 [[nodiscard]]
char const *hostname() const;
362 [[nodiscard]]
char const *port() const;
365 [[nodiscard]]
int PQXX_PURE backendpid() const &noexcept;
378 [[nodiscard]]
int PQXX_PURE sock() const &noexcept;
384 [[nodiscard]]
int PQXX_PURE protocol_version() const noexcept;
399 [[nodiscard]]
int PQXX_PURE server_version() const noexcept;
423 [[nodiscard]]
std::
string get_client_encoding() const;
430 void set_client_encoding(
zview encoding) &
432 set_client_encoding(encoding.c_str());
439 void set_client_encoding(
char const encoding[]) &;
442 [[nodiscard]]
int encoding_id()
const;
460 [[deprecated(
"To set session variables, use set_session_var.")]]
void
461 set_variable(std::string_view var, std::string_view value) &;
485 template<
typename TYPE>
492 internal::concat(
"Attempted to set variable ", var,
" to null.")};
494 exec(internal::concat(
"SET ", quote_name(var),
"=", quote(value)));
501 [[deprecated(
"Use get_var instead.")]] std::string
502 get_variable(std::string_view);
511 std::string get_var(std::string_view var);
520 template<
typename TYPE> TYPE
get_var_as(std::string_view var)
522 return from_string<TYPE>(get_var(var));
562 int await_notification();
577 int await_notification(std::time_t seconds,
long microseconds);
610 [[nodiscard]] std::string
618 char const user[],
char const password[],
char const *algorithm =
nullptr);
671 prepare(name.c_str(), definition.c_str());
678 void prepare(
char const name[],
char const definition[]) &;
688 void prepare(
char const definition[]) &;
692 void unprepare(std::string_view name);
701 [[nodiscard]] std::string adorn_name(std::string_view);
713 [[deprecated(
"Use std::string_view or pqxx:zview.")]] std::string
714 esc(
char const text[], std::size_t maxlen)
const
716 return esc(std::string_view{text, maxlen});
720 [[nodiscard]] std::string
esc(
char const text[])
const
722 return esc(std::string_view{text});
725 #if defined(PQXX_HAVE_SPAN)
738 [[nodiscard]] std::string_view
739 esc(std::string_view text, std::span<char> buffer)
741 auto const size{std::size(text)}, space{std::size(buffer)};
742 auto const needed{2 * size + 1};
744 throw range_error{internal::concat(
745 "Not enough room to escape string of ", size,
" byte(s): need ",
746 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
747 auto const data{buffer.data()};
748 return {data, esc_to_buf(text, data)};
756 [[nodiscard]] std::string esc(std::string_view text)
const;
758 #if defined(PQXX_HAVE_CONCEPTS)
761 template<binary DATA> [[nodiscard]] std::string esc(DATA
const &data)
const
763 return esc_raw(data);
767 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
780 template<binary DATA>
781 [[nodiscard]] zview esc(DATA
const &data, std::span<char> buffer)
const
783 auto const size{std::size(data)}, space{std::size(buffer)};
786 throw range_error{internal::concat(
787 "Not enough room to escape binary string of ", size,
" byte(s): need ",
788 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
790 std::basic_string_view<std::byte> view{std::data(data), std::size(data)};
791 auto const out{std::data(buffer)};
795 return zview{out, needed - 1};
800 [[deprecated(
"Use std::byte for binary data.")]] std::string
801 esc_raw(
unsigned char const bin[], std::size_t len)
const;
805 [[nodiscard]] std::string esc_raw(std::basic_string_view<std::byte>)
const;
807 #if defined(PQXX_HAVE_SPAN)
810 [[nodiscard]] std::string
811 esc_raw(std::basic_string_view<std::byte>, std::span<char> buffer)
const;
814 #if defined(PQXX_HAVE_CONCEPTS)
817 template<binary DATA>
818 [[nodiscard]] std::string esc_raw(DATA
const &data)
const
821 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
825 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
826 template<binary DATA>
828 [[nodiscard]] zview esc_raw(DATA
const &data, std::span<char> buffer)
const
838 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
841 #include "pqxx/internal/ignore-deprecated-pre.hxx"
842 return unesc_raw(text.
c_str());
843 #include "pqxx/internal/ignore-deprecated-post.hxx"
850 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
851 unesc_raw(
char const text[])
const;
862 [[nodiscard]] std::basic_string<std::byte>
865 std::basic_string<std::byte> buf;
872 [[deprecated(
"Use quote(std::basic_string_view<std::byte>).")]] std::string
873 quote_raw(
unsigned char const bin[], std::size_t len)
const;
876 std::string quote_raw(std::basic_string_view<std::byte>)
const;
878 #if defined(PQXX_HAVE_CONCEPTS)
881 template<binary DATA>
882 [[nodiscard]] std::string quote_raw(DATA
const &data)
const
885 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
891 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
898 [[nodiscard]] std::string quote_table(std::string_view name)
const;
910 [[nodiscard]] std::string quote_table(
table_path)
const;
921 template<PQXX_CHAR_STRINGS_ARG STRINGS>
922 inline std::string quote_columns(STRINGS
const &columns)
const;
930 [[nodiscard]]
inline std::string quote(T
const &t)
const;
932 [[deprecated(
"Use std::byte for binary data.")]] std::string
933 quote(binarystring
const &)
const;
937 [[nodiscard]] std::string
938 quote(std::basic_string_view<std::byte> bytes)
const;
967 [[nodiscard]] std::string
968 esc_like(std::string_view text,
char escape_char =
'\\')
const;
978 #if defined(_WIN32) || __has_include(<fcntl.h>)
984 void set_blocking(
bool block) &;
985 #endif // defined(_WIN32) || __has_include(<fcntl.h>)
1012 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
1021 [[nodiscard]] std::string connection_string()
const;
1054 return std::exchange(m_conn,
nullptr);
1066 explicit connection(internal::pq::PGconn *raw_conn) : m_conn{raw_conn} {}
1074 std::pair<bool, bool> poll_connect();
1077 void init(
char const options[]);
1079 void init(
char const *params[],
char const *values[]);
1080 void complete_init();
1083 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query,
1084 std::string_view desc =
""sv);
1086 void PQXX_PRIVATE set_up_state();
1088 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
1095 std::
size_t esc_to_buf(
std::string_view text,
char *buf) const;
1097 friend class internal::gate::const_connection_largeobject;
1098 char const *PQXX_PURE err_msg() const noexcept;
1100 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
1102 result exec_prepared(
std::string_view statement, internal::c_params const &);
1105 void check_movable() const;
1107 void check_overwritable() const;
1109 friend class internal::gate::connection_errorhandler;
1110 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
1111 void PQXX_PRIVATE unregister_errorhandler(errorhandler *) noexcept;
1113 friend class internal::gate::connection_transaction;
1114 result exec(
std::string_view,
std::string_view = ""sv);
1116 PQXX_PRIVATE exec(
std::shared_ptr<
std::
string>,
std::string_view = ""sv);
1118 void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;
1120 friend struct internal::gate::connection_stream_from;
1121 std::pair<
std::unique_ptr<
char,
void (*)(
void const *)>,
std::
size_t>
1124 friend class internal::gate::connection_stream_to;
1125 void PQXX_PRIVATE write_copy_line(
std::string_view);
1126 void PQXX_PRIVATE end_copy_write();
1128 friend class internal::gate::connection_largeobject;
1129 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
1131 friend class internal::gate::connection_notification_receiver;
1135 friend class internal::gate::connection_pipeline;
1136 void PQXX_PRIVATE start_exec(
char const query[]);
1137 bool PQXX_PRIVATE consume_input() noexcept;
1138 bool PQXX_PRIVATE is_busy() const noexcept;
1139 internal::pq::PGresult *get_result();
1141 friend class internal::gate::connection_dbtransaction;
1142 friend class internal::gate::connection_sql_cursor;
1144 result exec_params(
std::string_view query, internal::c_params const &args);
1147 internal::pq::PGconn *m_conn =
nullptr;
1161 using receiver_list =
1164 receiver_list m_receivers;
1167 int m_unique_id = 0;
1223 connecting(
zview connection_string =
""_zv);
1225 connecting(connecting
const &) =
delete;
1226 connecting(connecting &&) =
default;
1227 connecting &operator=(connecting
const &) =
delete;
1228 connecting &operator=(connecting &&) =
default;
1231 [[nodiscard]]
int sock() const &noexcept {
return m_conn.sock(); }
1249 [[nodiscard]] constexpr
bool done() const &noexcept
1251 return not m_reading and not m_writing;
1263 [[nodiscard]] connection produce() &&;
1267 bool m_reading{
false};
1268 bool m_writing{
true};
1288 std::string buf{
'\''};
1289 buf.resize(2 + 2 * std::size(text) + 1);
1290 auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
1291 auto const closing_quote{1 + content_bytes};
1292 buf[closing_quote] =
'\'';
1293 auto const end{closing_quote + 1};
1300 template<PQXX_CHAR_STRINGS_ARG STRINGS>
1304 ","sv, std::cbegin(columns), std::cend(columns),
1305 [
this](
auto col) {
return this->quote_name(*col); });
1309 #if defined(PQXX_HAVE_CONCEPTS)
1310 template<
internal::ZKey_ZValues MAPPING>
1315 std::vector<char const *> keys, values;
1316 if constexpr (std::ranges::sized_range<MAPPING>)
1318 auto const size{std::ranges::size(params) + 1};
1320 values.reserve(size);
1322 for (
auto const &[key, value] : params)
1327 keys.push_back(
nullptr);
1328 values.push_back(
nullptr);
1329 init(std::data(keys), std::data(values));
1331 #endif // PQXX_HAVE_CONCEPTS
Definition: connection.hxx:111
std::string quote_columns(STRINGS const &columns) const
Quote and comma-separate a series of column names.
Definition: connection.hxx:1301
Result set containing data returned by a query or command.
Definition: result.hxx:72
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:714
void set_session_var(std::string_view var, TYPE const &value)&
Set one of the session variables to a new value.
Definition: connection.hxx:486
constexpr bool done() const &noexcept
Is our connection finished?
Definition: connection.hxx:1249
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:87
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:158
Connection to a database.
Definition: connection.hxx:252
Internal items for libpqxx' own use. Do not use these yourself.
Definition: composite.hxx:83
A do-nothing flag that does not affect anything.
Definition: connection.hxx:139
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:126
constexpr bool wait_to_write() const &noexcept
Should we currently wait to be able to write to the socket?
Definition: connection.hxx:1240
internal::pq::PGconn * release_raw_connection()&&
Release the raw connection without closing it.
Definition: connection.hxx:1052
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:32
int sock() const &noexcept
Get the socket. The socket may change during the connection process.
Definition: connection.hxx:1231
Traits describing a type's "null value," if any.
Definition: strconv.hxx:92
~connection()
Definition: connection.hxx:299
error_verbosity
Error verbosity levels.
Definition: connection.hxx:209
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:411
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
void prepare(zview name, zview definition)&
Define a prepared statement.
Definition: connection.hxx:669
void check_version() noexcept
Definition: util.hxx:234
constexpr bool wait_to_read() const &noexcept
Should we currently wait to be able to read from the socket?
Definition: connection.hxx:1234
Base class for error-handler callbacks.
Definition: errorhandler.hxx:53
An ongoing, non-blocking stepping stone to a connection.
Definition: connection.hxx:1219
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition: connection.cxx:94
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:44
connection(zview options)
Connect to a database, using options string.
Definition: connection.hxx:265
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:420
skip_init
Flags for skipping initialisation of SSL-related libraries.
Definition: connection.hxx:136
The caller attempted to set a variable to null, which is not allowed.
Definition: except.hxx:115
Skip initialisation of OpenSSL library.
Definition: connection.hxx:142
std::basic_string_view< std::byte > binary_cast(TYPE const &data)
Cast binary data to a type that libpqxx will recognise as binary.
Definition: util.hxx:303
connection()
Definition: connection.hxx:255
Definition: notification.hxx:56
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition: zview.hxx:145
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:839
connection(char const options[])
Connect to a database, using options string.
Definition: connection.hxx:258
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition: connection.hxx:188
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:549
constexpr bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:518
Build a parameter list for a parameterised or prepared statement.
Definition: params.hxx:219
void PQXX_COLD skip_init_ssl(int flags) noexcept
Control OpenSSL/crypto library initialisation.
Definition: connection.cxx:83
constexpr char const * c_str() const &noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:96
std::string encrypt_password(zview user, zview password, zview algorithm)
Encrypt a password for a given user.
Definition: connection.hxx:612
std::basic_string< std::byte > unesc_bin(std::string_view text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:863
Skip initialisation of libcrypto.
Definition: connection.hxx:145
void prepare(zview definition)&
Definition: connection.hxx:689
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:720
TYPE get_var_as(std::string_view var)
Read currently applicable value of a variable.
Definition: connection.hxx:520
static connection seize_raw_connection(internal::pq::PGconn *raw_conn)
Seize control of a raw libpq connection.
Definition: connection.hxx:1041
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition: connection.hxx:1272