13 #ifndef PQXX_H_CONNECTION
14 #define PQXX_H_CONNECTION
16 #include "pqxx/compiler-public.hxx"
17 #include "pqxx/internal/compiler-internal-pre.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"
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>
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>
233 catch (std::exception
const &)
251 [[nodiscard]]
bool PQXX_PURE is_open() const noexcept;
254 void process_notice(
char const[]) noexcept;
259 void process_notice(
zview) noexcept;
262 void trace(std::FILE *) noexcept;
275 [[nodiscard]]
char const *dbname() const;
278 [[nodiscard]]
char const *username() const;
281 [[nodiscard]]
char const *hostname() const;
284 [[nodiscard]]
char const *port() const;
287 [[nodiscard]]
int PQXX_PURE backendpid() const noexcept;
305 [[nodiscard]]
int PQXX_PURE sock() const noexcept;
311 [[nodiscard]]
int PQXX_PURE protocol_version() const noexcept;
326 [[nodiscard]]
int PQXX_PURE server_version() const noexcept;
351 [[nodiscard]] std::
string get_client_encoding() const;
357 void set_client_encoding(
zview encoding)
359 set_client_encoding(encoding.c_str());
366 void set_client_encoding(
char const encoding[]);
369 [[nodiscard]]
int PQXX_PRIVATE encoding_id()
const;
389 void set_variable(std::string_view var, std::string_view value);
395 std::string get_variable(std::string_view);
428 int await_notification();
439 int await_notification(std::time_t seconds,
long microseconds);
473 [[nodiscard]] std::string
480 char const user[],
char const password[],
char const *algorithm =
nullptr);
540 void prepare(
char const name[],
char const definition[]);
550 void prepare(
char const definition[]);
554 void unprepare(std::string_view name);
562 [[nodiscard]] std::string adorn_name(std::string_view);
574 [[deprecated(
"Use std::string_view or pqxx:zview.")]] std::string
575 esc(
char const text[], std::size_t maxlen)
const
577 return esc(std::string_view{
text, maxlen});
581 [[nodiscard]] std::string
esc(
char const text[])
const
583 return esc(std::string_view{
text});
586 #if defined(PQXX_HAVE_SPAN)
600 [[nodiscard]] std::string_view
601 esc(std::string_view text, std::span<char> buffer)
603 auto const size{std::size(text)}, space{std::size(buffer)};
604 auto const needed{2 * size + 1};
606 throw range_error{internal::concat(
607 "Not enough room to escape string of ", size,
" byte(s): need ",
608 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
609 auto const data{buffer.data()};
610 return std::string_view{data, esc_to_buf(text, data)};
618 [[nodiscard]] std::string esc(std::string_view text)
const;
620 #if defined(PQXX_HAVE_CONCEPTS)
623 template<binary DATA> [[nodiscard]] std::string esc(DATA
const &data)
const
625 return esc_raw(data);
629 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
642 template<binary DATA>
643 [[nodiscard]] zview esc(DATA
const &data, std::span<char> buffer)
const
645 auto const size{std::size(data)}, space{std::size(buffer)};
648 throw range_error{internal::concat(
649 "Not enough room to escape binary string of ", size,
" byte(s): need ",
650 needed,
" bytes of buffer space, but buffer size is ", space,
".")};
652 std::basic_string_view<std::byte> view{std::data(data), std::size(data)};
653 auto const out{std::data(buffer)};
657 return zview{out, needed - 1};
662 [[deprecated(
"Use std::byte for binary data.")]] std::string
663 esc_raw(
unsigned char const bin[], std::size_t len)
const;
667 [[nodiscard]] std::string esc_raw(std::basic_string_view<std::byte>)
const;
669 #if defined(PQXX_HAVE_SPAN)
672 [[nodiscard]] std::string
673 esc_raw(std::basic_string_view<std::byte>, std::span<char> buffer)
const;
676 #if defined(PQXX_HAVE_CONCEPTS)
679 template<binary DATA>
680 [[nodiscard]] std::string esc_raw(DATA
const &data)
const
683 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
687 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
689 template<binary DATA>
690 [[nodiscard]] zview esc_raw(DATA
const &data, std::span<char> buffer)
const
700 [[nodiscard, deprecated(
"Use unesc_bin() instead.")]] std::string
703 #include "pqxx/internal/ignore-deprecated-pre.hxx"
704 return unesc_raw(
text.c_str());
705 #include "pqxx/internal/ignore-deprecated-post.hxx"
712 [[nodiscard, deprecated(
"Use unesc_bin() intead.")]] std::string
713 unesc_raw(
char const text[])
const;
724 [[nodiscard]] std::basic_string<std::byte>
727 std::basic_string<std::byte> buf;
734 [[deprecated(
"Use quote(std::basic_string_view<std::byte>).")]] std::string
735 quote_raw(
unsigned char const bin[], std::size_t len)
const;
738 std::string quote_raw(std::basic_string_view<std::byte>)
const;
740 #if defined(PQXX_HAVE_CONCEPTS)
743 template<binary DATA>
744 [[nodiscard]] std::string quote_raw(DATA
const &data)
const
747 std::basic_string_view<std::byte>{std::data(data), std::size(data)});
753 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
760 [[nodiscard]] std::string quote_table(std::string_view name)
const;
772 [[nodiscard]] std::string quote_table(
table_path)
const;
783 template<PQXX_CHAR_STRINGS_ARG STRINGS>
784 inline std::string quote_columns(STRINGS
const &columns)
const;
792 [[nodiscard]]
inline std::string quote(T
const &t)
const;
794 [[deprecated(
"Use std::byte for binary data.")]] std::string
795 quote(binarystring
const &)
const;
799 [[nodiscard]] std::string
800 quote(std::basic_string_view<std::byte> bytes)
const;
827 [[nodiscard]] std::string
828 esc_like(std::string_view text,
char escape_char =
'\\')
const;
863 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
872 [[nodiscard]] std::string connection_string()
const;
887 void init(
char const options[]);
889 void init(
char const *params[],
char const *values[]);
890 void complete_init();
893 void wait_read(std::time_t seconds,
long microseconds)
const;
896 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query,
897 std::string_view desc =
""sv);
899 void PQXX_PRIVATE set_up_state();
901 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
908 std::
size_t esc_to_buf(std::string_view text,
char *buf) const;
910 friend class internal::gate::const_connection_largeobject;
911 char const *PQXX_PURE err_msg() const noexcept;
913 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
915 result exec_prepared(std::string_view statement, internal::c_params const &);
918 void check_movable() const;
920 void check_overwritable() const;
922 friend class internal::gate::connection_errorhandler;
923 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
924 void PQXX_PRIVATE unregister_errorhandler(
errorhandler *) noexcept;
926 friend class internal::gate::connection_transaction;
927 result PQXX_PRIVATE exec(std::string_view, std::string_view = ""sv);
929 PQXX_PRIVATE exec(std::shared_ptr<std::
string>, std::string_view = ""sv);
933 friend class internal::gate::connection_stream_from;
934 std::pair<std::unique_ptr<
char, std::function<
void(
char *)>>, std::
size_t>
935 PQXX_PRIVATE read_copy_line();
937 friend class internal::gate::connection_stream_to;
938 void PQXX_PRIVATE write_copy_line(std::string_view);
939 void PQXX_PRIVATE end_copy_write();
941 friend class internal::gate::connection_largeobject;
942 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
944 friend class internal::gate::connection_notification_receiver;
948 friend class internal::gate::connection_pipeline;
949 void PQXX_PRIVATE start_exec(
char const query[]);
950 bool PQXX_PRIVATE consume_input() noexcept;
951 bool PQXX_PRIVATE is_busy() const noexcept;
952 internal::pq::PGresult *get_result();
954 friend class internal::gate::connection_dbtransaction;
955 friend class internal::gate::connection_sql_cursor;
957 result exec_params(std::string_view query, internal::c_params const &args);
960 internal::pq::PGconn *m_conn =
nullptr;
974 using receiver_list =
977 receiver_list m_receivers;
988 template<typename T> inline std::
string connection::quote(T const &t)
const
1004 std::string buf{
'\''};
1005 buf.resize(2 + 2 * std::size(
text) + 1);
1006 auto const content_bytes{esc_to_buf(
text, buf.data() + 1)};
1007 auto const closing_quote{1 + content_bytes};
1008 buf[closing_quote] =
'\'';
1009 auto const end{closing_quote + 1};
1016 template<PQXX_CHAR_STRINGS_ARG STRINGS>
1020 ","sv, std::cbegin(columns), std::cend(columns),
1021 [
this](
auto col) {
return this->quote_name(*col); });
1025 #if defined(PQXX_HAVE_CONCEPTS)
1026 template<
internal::ZKey_ZValues MAPPING>
1031 std::vector<char const *> keys, values;
1032 if constexpr (std::ranges::sized_range<MAPPING>)
1034 auto const size{std::ranges::size(
params) + 1};
1036 values.reserve(size);
1038 for (
auto const &[key, value] : params)
1043 keys.push_back(
nullptr);
1044 values.push_back(
nullptr);
1045 init(std::data(keys), std::data(values));
1053 PQXX_LIBEXPORT
void wait_read(internal::pq::PGconn
const *);
1055 internal::pq::PGconn
const *, std::time_t seconds,
long microseconds);
1056 PQXX_LIBEXPORT
void wait_write(internal::pq::PGconn
const *);
1059 #include "pqxx/internal/compiler-internal-post.hxx"
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
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:42
std::initializer_list< std::string_view > table_path
Representation of a PostgreSQL table path.
Definition: connection.hxx:119
void check_version()
Definition: util.hxx:162
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:507
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:230
bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:357
error_verbosity
Error verbosity levels.
Definition: connection.hxx:141
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition: connection.cxx:95
Internal items for libpqxx' own use. Do not use these yourself.
Definition: composite.hxx:74
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:176
void esc_bin(std::basic_string_view< std::byte > binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:145
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:326
void wait_write(internal::pq::PGconn const *)
Definition: connection.cxx:1030
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition: zview.hxx:131
void wait_read(internal::pq::PGconn const *)
Definition: connection.cxx:1011
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:335
Definition: connection.hxx:95
Connection to a database.
Definition: connection.hxx:181
std::string encrypt_password(zview user, zview password, zview algorithm)
Encrypt a password for a given user.
Definition: connection.hxx:474
connection(char const options[])
Connect to a database, using options string.
Definition: connection.hxx:186
connection()
Definition: connection.hxx:183
~connection()
Definition: connection.hxx:227
void prepare(zview name, zview definition)
Define a prepared statement.
Definition: connection.hxx:531
std::string quote_columns(STRINGS const &columns) const
Quote and comma-separate a series of column names.
Definition: connection.hxx:1017
connection(zview options)
Connect to a database, using options string.
Definition: connection.hxx:193
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:725
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:581
void prepare(zview definition)
Definition: connection.hxx:551
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:701
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:575
connection & operator=(connection const &)=delete
connection(connection const &)=delete
Base class for error-handler callbacks.
Definition: errorhandler.hxx:53
Definition: notification.hxx:56
Build a parameter list for a parameterised or prepared statement.
Definition: params.hxx:214
Result set containing data returned by a query or command.
Definition: result.hxx:71
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:76
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:40
constexpr char const * c_str() const noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:87