13 #ifndef PQXX_H_CONNECTION 14 #define PQXX_H_CONNECTION 19 #include <initializer_list> 23 #include <string_view> 27 #if defined(PQXX_HAVE_CONCEPTS) && __has_include(<ranges>) 31 #include "pqxx/errorhandler.hxx" 32 #include "pqxx/except.hxx" 33 #include "pqxx/internal/concat.hxx" 34 #include "pqxx/params.hxx" 35 #include "pqxx/separated_list.hxx" 36 #include "pqxx/strconv.hxx" 37 #include "pqxx/types.hxx" 38 #include "pqxx/util.hxx" 39 #include "pqxx/zview.hxx" 76 #if defined(PQXX_HAVE_CONCEPTS) 79 concept ZKey_ZValues = std::ranges::input_range<T> and requires(T t)
83 std::get<0>(*std::cbegin(t))
86 std::get<1>(*std::cbegin(t))
88 } and std::tuple_size_v<typename std::ranges::iterator_t<T>::value_type>
90 #endif // PQXX_HAVE_CONCEPTS 96 class connection_dbtransaction;
97 class connection_errorhandler;
98 class connection_largeobject;
99 class connection_notification_receiver;
100 class connection_pipeline;
101 class connection_sql_cursor;
102 class connection_stream_from;
103 class connection_stream_to;
104 class connection_transaction;
105 class const_connection_largeobject;
124 deprecated(
"Use connection::encrypt_password instead.")]] std::string
130 deprecated(
"Use connection::encrypt_password instead.")]]
inline std::string
133 #include "pqxx/internal/ignore-deprecated-pre.hxx" 135 #include "pqxx/internal/ignore-deprecated-post.hxx" 206 #if defined(PQXX_HAVE_CONCEPTS) 223 template<
internal::ZKey_ZValues MAPPING>
225 #endif // PQXX_HAVE_CONCEPTS 233 catch (std::exception
const &)
241 connection &operator=(connection &&rhs);
243 connection(connection
const &) =
delete;
244 connection &operator=(connection
const &) =
delete;
252 [[nodiscard]]
bool PQXX_PURE is_open()
const noexcept;
255 void process_notice(
char const[]) noexcept;
260 void process_notice(
zview) noexcept;
263 void trace(std::FILE *) noexcept;
275 [[nodiscard]]
char const *dbname()
const;
279 [[nodiscard]]
char const *username()
const;
282 [[nodiscard]]
char const *hostname()
const;
285 [[nodiscard]]
char const *port()
const;
288 [[nodiscard]]
int PQXX_PURE backendpid()
const &noexcept;
301 [[nodiscard]]
int PQXX_PURE sock()
const &noexcept;
307 [[nodiscard]]
int PQXX_PURE protocol_version()
const noexcept;
322 [[nodiscard]]
int PQXX_PURE server_version()
const noexcept;
346 [[nodiscard]] std::string get_client_encoding()
const;
355 set_client_encoding(encoding.c_str());
362 void set_client_encoding(
char const encoding[]) &;
365 [[nodiscard]]
int PQXX_PRIVATE encoding_id()
const;
385 void set_variable(std::string_view var, std::string_view value) &;
391 std::string get_variable(std::string_view);
432 int await_notification();
447 int await_notification(std::time_t seconds,
long microseconds);
480 [[nodiscard]] std::string
488 char const user[],
char const password[],
char const *algorithm =
nullptr);
541 prepare(name.c_str(), definition.c_str());
548 void prepare(
char const name[],
char const definition[]) &;
558 void prepare(
char const definition[]) &;
562 void unprepare(std::string_view name);
570 [[nodiscard]] std::string adorn_name(std::string_view);
582 [[deprecated(
"Use std::string_view or pqxx:zview.")]] std::string
583 esc(
char const text[], std::size_t maxlen)
const 585 return esc(std::string_view{text, maxlen});
589 [[nodiscard]] std::string
esc(
char const text[])
const 591 return esc(std::string_view{text});
594 #if defined(PQXX_HAVE_SPAN) 607 [[nodiscard]] std::string_view
608 esc(std::string_view
text, std::span<char> buffer)
610 auto const size{std::size(text)}, space{std::size(buffer)};
611 auto const needed{2 * size + 1};
614 "Not enough room to escape string of ", size,
" byte(s): need ",
615 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
616 auto const data{buffer.data()};
617 return {data, esc_to_buf(text, data)};
625 [[nodiscard]] std::string esc(std::string_view text)
const;
627 #if defined(PQXX_HAVE_CONCEPTS) 630 template<binary DATA> [[nodiscard]] std::string esc(DATA
const &data)
const 632 return esc_raw(data);
636 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN) 649 template<binary DATA>
650 [[nodiscard]]
zview esc(DATA
const &data, std::span<char> buffer)
const 652 auto const size{std::size(data)}, space{std::size(buffer)};
656 "Not enough room to escape binary string of ", size,
" byte(s): need ",
657 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
659 std::basic_string_view<std::byte> view{std::data(data), std::size(data)};
660 auto const out{std::data(buffer)};
664 return zview{out, needed - 1};
669 [[deprecated(
"Use std::byte for binary data.")]] std::string
670 esc_raw(
unsigned char const bin[], std::size_t len)
const;
674 [[nodiscard]] std::string esc_raw(std::basic_string_view<std::byte>)
const;
676 #if defined(PQXX_HAVE_SPAN) 679 [[nodiscard]] std::string
680 esc_raw(std::basic_string_view<std::byte>, std::span<char> buffer)
const;
683 #if defined(PQXX_HAVE_CONCEPTS) 686 template<binary DATA>
687 [[nodiscard]] std::string esc_raw(DATA
const &data)
const 690 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
694 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN) 695 template<binary DATA>
697 [[nodiscard]]
zview esc_raw(DATA
const &data, std::span<char> buffer)
const 707 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
710 #include "pqxx/internal/ignore-deprecated-pre.hxx" 711 return unesc_raw(text.
c_str());
712 #include "pqxx/internal/ignore-deprecated-post.hxx" 719 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
720 unesc_raw(
char const text[])
const;
731 [[nodiscard]] std::basic_string<std::byte>
734 std::basic_string<std::byte> buf;
741 [[deprecated(
"Use quote(std::basic_string_view<std::byte>).")]] std::string
742 quote_raw(
unsigned char const bin[], std::size_t len)
const;
745 std::string quote_raw(std::basic_string_view<std::byte>)
const;
747 #if defined(PQXX_HAVE_CONCEPTS) 750 template<binary DATA>
751 [[nodiscard]] std::string quote_raw(DATA
const &data)
const 754 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
760 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
767 [[nodiscard]] std::string quote_table(std::string_view name)
const;
779 [[nodiscard]] std::string quote_table(
table_path)
const;
790 template<PQXX_CHAR_STRINGS_ARG STRINGS>
791 inline std::string quote_columns(STRINGS
const &columns)
const;
799 [[nodiscard]]
inline std::string quote(T
const &t)
const;
801 [[deprecated(
"Use std::byte for binary data.")]] std::string
806 [[nodiscard]] std::string
807 quote(std::basic_string_view<std::byte> bytes)
const;
836 [[nodiscard]] std::string
837 esc_like(std::string_view text,
char escape_char =
'\\')
const;
847 #if defined(_WIN32) || __has_include(<fcntl.h>) 848 void set_blocking(
bool block) &;
850 #endif // defined(_WIN32) || __has_include(<fcntl.h>) 877 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
886 [[nodiscard]] std::string connection_string()
const;
905 connection(connect_mode,
zview connection_string);
913 std::pair<bool, bool> poll_connect();
916 void init(
char const options[]);
918 void init(
char const *params[],
char const *values[]);
919 void complete_init();
922 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query,
923 std::string_view desc =
""sv);
925 void PQXX_PRIVATE set_up_state();
927 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
934 std::
size_t esc_to_buf(
std::string_view text,
char *buf) const;
936 friend class internal::gate::const_connection_largeobject;
937 char const *PQXX_PURE err_msg() const noexcept;
939 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
941 result exec_prepared(
std::string_view statement, internal::c_params const &);
944 void check_movable() const;
946 void check_overwritable() const;
948 friend class internal::gate::connection_errorhandler;
949 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
950 void PQXX_PRIVATE unregister_errorhandler(errorhandler *) noexcept;
952 friend class internal::gate::connection_transaction;
953 result PQXX_PRIVATE exec(
std::string_view,
std::string_view = ""sv);
955 PQXX_PRIVATE exec(
std::shared_ptr<
std::
string>,
std::string_view = ""sv);
957 void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;
959 friend class internal::gate::connection_stream_from;
960 std::pair<
std::unique_ptr<
char,
std::function<
void(
char *)>>,
std::
size_t>
961 PQXX_PRIVATE read_copy_line();
963 friend class internal::gate::connection_stream_to;
964 void PQXX_PRIVATE write_copy_line(
std::string_view);
965 void PQXX_PRIVATE end_copy_write();
967 friend class internal::gate::connection_largeobject;
968 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
970 friend class internal::gate::connection_notification_receiver;
974 friend class internal::gate::connection_pipeline;
975 void PQXX_PRIVATE start_exec(
char const query[]);
976 bool PQXX_PRIVATE consume_input() noexcept;
977 bool PQXX_PRIVATE is_busy() const noexcept;
978 internal::pq::PGresult *get_result();
980 friend class internal::gate::connection_dbtransaction;
981 friend class internal::gate::connection_sql_cursor;
983 result exec_params(
std::string_view query, internal::c_params const &args);
986 internal::pq::PGconn *m_conn =
nullptr;
1000 using receiver_list =
1003 receiver_list m_receivers;
1006 int m_unique_id = 0;
1062 connecting(
zview connection_string =
""_zv);
1064 connecting(connecting
const &) =
delete;
1065 connecting(connecting &&) =
default;
1066 connecting &operator=(connecting
const &) =
delete;
1067 connecting &operator=(connecting &&) =
default;
1070 [[nodiscard]]
int sock() const &noexcept {
return m_conn.sock(); }
1082 [[nodiscard]]
bool done() const &noexcept
1084 return not m_reading and not m_writing;
1096 [[nodiscard]] connection produce() &&;
1100 bool m_reading{
false};
1101 bool m_writing{
true};
1121 std::string buf{
'\''};
1122 buf.resize(2 + 2 * std::size(text) + 1);
1123 auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
1124 auto const closing_quote{1 + content_bytes};
1125 buf[closing_quote] =
'\'';
1126 auto const end{closing_quote + 1};
1133 template<PQXX_CHAR_STRINGS_ARG STRINGS>
1137 ","sv, std::cbegin(columns), std::cend(columns),
1138 [
this](
auto col) {
return this->quote_name(*col); });
1142 #if defined(PQXX_HAVE_CONCEPTS) 1143 template<
internal::ZKey_ZValues MAPPING>
1148 std::vector<char const *> keys, values;
1149 if constexpr (std::ranges::sized_range<MAPPING>)
1151 auto const size{std::ranges::size(params) + 1};
1153 values.reserve(size);
1155 for (
auto const &[key, value] : params)
1160 keys.push_back(
nullptr);
1161 values.push_back(
nullptr);
1162 init(std::data(keys), std::data(values));
1164 #endif // PQXX_HAVE_CONCEPTS 1172 int fd,
bool for_read,
bool for_write,
unsigned seconds = 1,
1173 unsigned microseconds = 0);
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:72
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:148
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:54
Base class for error-handler callbacks.
Definition: errorhandler.hxx:49
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:179
An ongoing, non-blocking stepping stone to a connection.
Definition: connection.hxx:1058
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:406
Result set containing data returned by a query or command.
Definition: result.hxx:67
bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:364
~connection()
Definition: connection.hxx:227
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition: connection.hxx:1105
connection(char const options[])
Connect to a database, using options string.
Definition: connection.hxx:186
bool wait_to_read() const &noexcept
Should we currently wait to be able to read from the socket?
Definition: connection.hxx:1073
Definition: notification.hxx:52
Definition: connection.hxx:94
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:708
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:732
Build a parameter list for a parameterised or prepared statement.
Definition: params.hxx:213
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:39
bool done() const &noexcept
Is our connection finished?
Definition: connection.hxx:1082
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:397
void set_client_encoding(zview encoding) &
Set client-side character encoding, by name.
Definition: connection.hxx:353
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:583
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:289
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition: connection.hxx:119
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition: connection.cxx:101
std::string quote_columns(STRINGS const &columns) const
Quote and comma-separate a series of column names.
Definition: connection.hxx:1134
void prepare(zview definition) &
Definition: connection.hxx:559
connection(zview options)
Connect to a database, using options string.
Definition: connection.hxx:193
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:589
Internal items for libpqxx' own use. Do not use these yourself.
Definition: composite.hxx:79
Connection to a database.
Definition: connection.hxx:180
void prepare(zview name, zview definition) &
Define a prepared statement.
Definition: connection.hxx:539
error_verbosity
Error verbosity levels.
Definition: connection.hxx:140
std::string encrypt_password(zview user, zview password, zview algorithm)
Encrypt a password for a given user.
Definition: connection.hxx:482
connection()
Definition: connection.hxx:183
Traits describing a type's "null value," if any.
Definition: strconv.hxx:88
void check_version()
Definition: util.hxx:221
constexpr char const * c_str() const &noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:85
bool wait_to_write() const &noexcept
Should we currently wait to be able to write to the socket?
Definition: connection.hxx:1076
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition: zview.hxx:136
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:22
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:528
int sock() const &noexcept
Get the socket. The socket may change during the connection process.
Definition: connection.hxx:1070
Something is out of range, similar to std::out_of_range.
Definition: except.hxx:189
void wait_fd(int fd, bool for_read, bool for_write, unsigned seconds=1, unsigned microseconds=0)
Wait for a socket to be ready for reading/writing, or timeout.
Definition: connection.cxx:1095