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"
79#if defined(PQXX_HAVE_CONCEPTS)
87 std::get<0>(*std::cbegin(
t))
90 std::get<1>(*std::cbegin(
t))
92}
and std::tuple_size_v<typename std::ranges::iterator_t<T>::value_type> == 2;
110class connection_dbtransaction;
111class connection_errorhandler;
112class connection_largeobject;
113class connection_notification_receiver;
114class connection_pipeline;
115class connection_sql_cursor;
116struct connection_stream_from;
117class connection_stream_to;
118class connection_transaction;
119class const_connection_largeobject;
258#if defined(PQXX_HAVE_CONCEPTS)
275 template<
internal::ZKey_ZValues MAPPING>
285 catch (std::exception
const &)
412 set_client_encoding(
encoding.c_str());
419 void set_client_encoding(
char const encoding[]) &;
448 template<
typename TYPE>
455 internal::concat(
"Attempted to set variable ",
var,
" to null.")};
457 exec(internal::concat(
"SET ", quote_name(
var),
"=", quote(value)));
467 std::string get_var(std::string_view
var);
518 int await_notification();
634 void prepare(
char const name[],
char const definition[]) &;
648 void unprepare(std::string_view name);
657 [[
nodiscard]] std::string adorn_name(std::string_view);
667 return esc(std::string_view{
text});
670#if defined(PQXX_HAVE_SPAN)
684 esc(std::string_view
text, std::span<char>
buffer)
687 auto const needed{2 * size + 1};
689 throw range_error{internal::concat(
690 "Not enough room to escape string of ", size,
" byte(s): need ",
691 needed,
" bytes of buffer space, but buffer size is ",
space,
".")};
692 auto const data{
buffer.data()};
693 return {data, esc_to_buf(
text, data)};
703#if defined(PQXX_HAVE_CONCEPTS)
706 template<binary DATA> [[
nodiscard]] std::string esc(
DATA const &data)
const
708 return esc_raw(data);
712#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
725 template<binary DATA>
728 auto const size{std::size(data)},
space{std::size(
buffer)};
731 throw range_error{internal::concat(
732 "Not enough room to escape binary string of ", size,
" byte(s): need ",
733 needed,
" bytes of buffer space, but buffer size is ",
space,
".")};
735 bytes_view view{std::data(data), std::size(data)};
745 [[deprecated(
"Use std::byte for binary data.")]] std::string
746 esc_raw(
unsigned char const bin[], std::size_t
len)
const;
752#if defined(PQXX_HAVE_SPAN)
758#if defined(PQXX_HAVE_CONCEPTS)
761 template<binary DATA>
764 return esc_raw(
bytes_view{std::data(data), std::size(data)});
768#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
770 template<binary DATA>
797#if defined(PQXX_HAVE_CONCEPTS)
800 template<binary DATA>
803 return quote_raw(
bytes_view{std::data(data), std::size(data)});
816 [[
nodiscard]] std::string quote_table(std::string_view name)
const;
839 template<PQXX_CHAR_STRINGS_ARG STRINGS>
840 inline std::string quote_columns(
STRINGS const &columns)
const;
848 [[
nodiscard]]
inline std::string quote(T
const &
t)
const;
850 [[deprecated(
"Use std::byte for binary data.")]] std::string
851 quote(binarystring
const &)
const;
892 [[deprecated(
"Use std::string_view or pqxx:zview.")]] std::string
902 [[
nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
905#include "pqxx/internal/ignore-deprecated-pre.hxx"
906 return unesc_raw(
text.c_str());
907#include "pqxx/internal/ignore-deprecated-post.hxx"
914 [[
nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
915 unesc_raw(
char const text[])
const;
918 [[deprecated(
"Use quote(bytes_view).")]] std::string
919 quote_raw(
unsigned char const bin[], std::size_t
len)
const;
929#if defined(_WIN32) || __has_include(<fcntl.h>)
963 [[
nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
972 [[
nodiscard]] std::string connection_string()
const;
1005 return std::exchange(m_conn,
nullptr);
1022 [[deprecated(
"To set session variables, use set_session_var.")]]
void
1023 set_variable(std::string_view
var, std::string_view value) &;
1029 [[deprecated(
"Use get_var instead.")]] std::string
1030 get_variable(std::string_view);
1041 explicit connection(internal::pq::PGconn *raw_conn) : m_conn{raw_conn} {}
1049 std::pair<bool, bool> poll_connect();
1052 void init(
char const options[]);
1054 void init(
char const *params[],
char const *
values[]);
1055 void complete_init();
1058 internal::pq::PGresult *
pgr, std::shared_ptr<std::string>
const &query,
1059 std::string_view
desc =
""sv);
1070 std::
size_t esc_to_buf(std::string_view
text,
char *
buf)
const;
1080 void check_movable()
const;
1082 void check_overwritable()
const;
1089 result exec(std::string_view, std::string_view = ""
sv);
1091 exec(std::shared_ptr<std::
string>
const &, std::string_view = ""
sv);
1102 std::pair<std::unique_ptr<
char,
void (*)(
void const *)>, std::
size_t>
1110 internal::pq::
PGconn *raw_connection()
const {
return m_conn; }
1112 friend class internal::gate::connection_notification_receiver;
1116 friend class internal::gate::connection_pipeline;
1120 internal::pq::
PGresult *get_result();
1128 internal::pq::
PGconn *m_conn =
nullptr;
1142 using receiver_list =
1145 receiver_list m_receivers;
1148 int m_unique_id = 0;
1248 bool m_reading{
false};
1249 bool m_writing{
true};
1269 std::string
buf{
'\''};
1270 buf.resize(2 + 2 * std::size(
text) + 1);
1281template<PQXX_CHAR_STRINGS_ARG STRINGS>
1285 ","sv, std::cbegin(columns), std::cend(columns),
1286 [
this](
auto col) {
return this->quote_name(*col); });
1290#if defined(PQXX_HAVE_CONCEPTS)
1291template<
internal::ZKey_ZValues MAPPING>
1296 std::vector<char const *> keys,
values;
1297 if constexpr (std::ranges::sized_range<MAPPING>)
1299 auto const size{std::ranges::size(
params) + 1};
1303 for (
auto const &[
key, value] : params)
1308 keys.push_back(
nullptr);
1309 values.push_back(
nullptr);
1310 init(std::data(keys), std::data(
values));
1317 deprecated(
"Use connection::encrypt_password instead.")]] std::string
1323 deprecated(
"Use connection::encrypt_password instead.")]]
inline std::string
1326#include "pqxx/internal/ignore-deprecated-pre.hxx"
1328#include "pqxx/internal/ignore-deprecated-post.hxx"
The home of all libpqxx classes, functions, templates, etc.
Definition array.hxx:33
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
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition connection.cxx:94
constexpr char array_separator
Element separator between SQL array elements of this type.
Definition strconv.hxx:557
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:381
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:371
void skip_init_ssl() noexcept
Control initialisation of OpenSSL and libcrypto libraries.
Definition connection.hxx:170
bytes_view binary_cast(TYPE const &data)
Cast binary data to a type that libpqxx will recognise as binary.
Definition util.hxx:407
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition connection.hxx:185
void check_version() noexcept
Definition util.hxx:234
constexpr bool is_null(TYPE const &value) noexcept
Is value null?
Definition strconv.hxx:513
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:134
@ crypto
Skip initialisation of libcrypto.
Definition connection.hxx:142
@ openssl
Skip initialisation of OpenSSL library.
Definition connection.hxx:139
@ nothing
A do-nothing flag that does not affect anything.
Definition connection.hxx:136
error_verbosity
Error verbosity levels.
Definition connection.hxx:190
Internal items for libpqxx' own use. Do not use these yourself.
Definition composite.hxx:84
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition util.cxx:165
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:514
void PQXX_COLD skip_init_ssl(int skips) noexcept
Control OpenSSL/crypto library initialisation.
Definition connection.cxx:83
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition zview.hxx:145
void 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:523
Definition connection.hxx:109
Connection to a database.
Definition connection.hxx:233
std::string encrypt_password(zview user, zview password, zview algorithm)
Encrypt a password for a given user.
Definition connection.hxx:568
void prepare(zview definition) &
Definition connection.hxx:645
connection(char const options[])
Connect to a database, using options string.
Definition connection.hxx:238
connection & operator=(connection const &)=delete
TYPE get_var_as(std::string_view var)
Read currently applicable value of a variable.
Definition connection.hxx:476
connection()
Definition connection.hxx:235
~connection()
Definition connection.hxx:279
bytes unesc_bin(std::string_view text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition connection.hxx:786
std::string quote_columns(STRINGS const &columns) const
Quote and comma-separate a series of column names.
Definition connection.hxx:1282
connection(zview options)
Connect to a database, using options string.
Definition connection.hxx:245
internal::pq::PGconn * release_raw_connection() &&
Release the raw connection without closing it.
Definition connection.hxx:1003
static connection seize_raw_connection(internal::pq::PGconn *raw_conn)
Seize control of a raw libpq connection.
Definition connection.hxx:992
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition connection.hxx:665
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition connection.hxx:903
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:893
void prepare(zview name, zview definition) &
Define a prepared statement.
Definition connection.hxx:625
void set_session_var(std::string_view var, TYPE const &value) &
Set one of the session variables to a new value.
Definition connection.hxx:449
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition connection.hxx:1253
connection(connection const &)=delete
An ongoing, non-blocking stepping stone to a connection.
Definition connection.hxx:1201
connecting(connecting &&)=default
int sock() const &noexcept
Get the socket. The socket may change during the connection process.
Definition connection.hxx:1212
constexpr bool done() const &noexcept
Is our connection finished?
Definition connection.hxx:1230
connecting & operator=(connecting const &)=delete
connecting(connecting const &)=delete
constexpr bool wait_to_write() const &noexcept
Should we currently wait to be able to write to the socket?
Definition connection.hxx:1221
void process() &
Progress towards completion (but don't block).
connecting & operator=(connecting &&)=default
constexpr bool wait_to_read() const &noexcept
Should we currently wait to be able to read from the socket?
Definition connection.hxx:1215
connecting(zview connection_string=""_zv)
Start connecting.
connection produce() &&
Produce the completed connection object.
Base class for error-handler callbacks.
Definition errorhandler.hxx:54
The caller attempted to set a variable to null, which is not allowed.
Definition except.hxx:116
Definition notification.hxx:57
Build a parameter list for a parameterised or prepared statement.
Definition params.hxx:46
Result set containing data returned by a query or command.
Definition result.hxx:73
Traits describing a type's "null value," if any.
Definition strconv.hxx:91
Interface definition (and common code) for "transaction" classes.
Definition transaction_base.hxx:88
Marker-type wrapper: zero-terminated std::string_view.
Definition zview.hxx:38