13 #ifndef PQXX_H_CONNECTION
14 #define PQXX_H_CONNECTION
16 #include "pqxx/compiler-public.hxx"
17 #include "pqxx/internal/compiler-internal-pre.hxx"
25 #include <string_view>
28 #if __has_include(<ranges>)
32 #include "pqxx/errorhandler.hxx"
33 #include "pqxx/except.hxx"
34 #include "pqxx/prepared_statement.hxx"
35 #include "pqxx/strconv.hxx"
36 #include "pqxx/util.hxx"
37 #include "pqxx/zview.hxx"
71 #if defined(PQXX_HAVE_CONCEPTS)
74 concept ZKey_ZValues = std::ranges::input_range<T> and requires()
76 {std::tuple_size<typename std::ranges::iterator_t<T>::value_type>::value};
78 and std::tuple_size_v<typename std::ranges::iterator_t<T>::value_type> == 2 and
82 std::get<0>(*std::cbegin(t))
86 std::get<1>(*std::cbegin(t))
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;
112 [[nodiscard]] std::string PQXX_LIBEXPORT
185 connection(connection &&rhs);
187 #if defined(PQXX_HAVE_CONCEPTS)
204 template<
internal::ZKey_ZValues MAPPING>
205 inline connection(MAPPING
const ¶ms);
206 #endif // PQXX_HAVE_CONCEPTS
214 catch (std::exception
const &)
232 [[nodiscard]]
bool PQXX_PURE is_open() const noexcept;
235 void process_notice(
char const[]) noexcept;
240 void process_notice(
zview) noexcept;
243 void trace(std::FILE *) noexcept;
255 [[nodiscard]]
char const *dbname() const;
259 [[nodiscard]]
char const *username() const;
262 [[nodiscard]]
char const *hostname() const;
265 [[nodiscard]]
char const *port() const;
268 [[nodiscard]]
int PQXX_PURE backendpid() const noexcept;
286 [[nodiscard]]
int PQXX_PURE sock() const noexcept;
292 [[nodiscard]]
int PQXX_PURE protocol_version() const noexcept;
307 [[nodiscard]]
int PQXX_PURE server_version() const noexcept;
331 [[nodiscard]] std::
string get_client_encoding() const;
338 void set_client_encoding(
zview encoding)
340 set_client_encoding(encoding.c_str());
347 void set_client_encoding(
char const encoding[]);
350 [[nodiscard]]
int PQXX_PRIVATE encoding_id()
const;
370 void set_variable(std::string_view var, std::string_view value);
376 std::string get_variable(std::string_view);
409 int await_notification();
420 int await_notification(std::time_t seconds,
long microseconds);
451 char const user[],
char const password[],
char const *algorithm =
nullptr);
452 [[nodiscard]] std::string
508 void prepare(
char const name[],
char const definition[]);
523 void prepare(
char const definition[]);
527 void unprepare(std::string_view name);
537 [[nodiscard]] std::string adorn_name(std::string_view);
549 [[nodiscard]] std::string
esc(
char const text[], std::size_t maxlen)
const
551 return esc(std::string_view(text, maxlen));
555 [[nodiscard]] std::string
esc(
char const text[])
const
557 return esc(std::string_view(text));
564 [[nodiscard]] std::string esc(std::string_view text)
const;
569 [[nodiscard]] std::string
570 esc_raw(
unsigned char const bin[], std::size_t len)
const;
573 [[nodiscard]] std::string esc_raw(std::basic_string_view<std::byte>)
const;
581 return unesc_raw(text.
c_str());
588 [[nodiscard]] std::string unesc_raw(
char const text[])
const;
593 [[nodiscard]] std::string
594 quote_raw(
unsigned char const bin[], std::size_t len)
const;
597 [[nodiscard]] std::string quote_raw(std::basic_string_view<std::byte>)
const;
600 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
607 [[nodiscard]]
inline std::string quote(T
const &t)
const;
610 [[nodiscard]] std::string quote(
binarystring const &)
const;
612 [[nodiscard]] std::string
613 quote(std::basic_string_view<std::byte> bytes)
const;
639 [[nodiscard]] std::string
640 esc_like(std::string_view text,
char escape_char =
'\\')
const;
675 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
684 [[nodiscard]] std::string connection_string()
const;
694 void init(
char const options[]);
696 void init(
char const *params[],
char const *values[]);
697 void complete_init();
699 void wait_read()
const;
700 void wait_read(std::time_t seconds,
long microseconds)
const;
703 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query);
705 void PQXX_PRIVATE set_up_state();
707 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
714 std::
size_t esc_to_buf(std::string_view text,
char *buf) const;
716 friend class internal::gate::const_connection_largeobject;
717 char const *PQXX_PURE err_msg() const noexcept;
719 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
721 result exec_prepared(std::string_view statement, internal::params const &);
724 void check_movable() const;
726 void check_overwritable() const;
728 friend class internal::gate::connection_errorhandler;
729 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
730 void PQXX_PRIVATE unregister_errorhandler(
errorhandler *) noexcept;
732 friend class internal::gate::connection_transaction;
733 result PQXX_PRIVATE exec(std::string_view);
734 result PQXX_PRIVATE exec(std::shared_ptr<std::
string>);
738 friend class internal::gate::connection_stream_from;
739 std::pair<std::unique_ptr<
char, std::function<
void(
char *)>>, std::
size_t>
740 PQXX_PRIVATE read_copy_line();
742 friend class internal::gate::connection_stream_to;
743 void PQXX_PRIVATE write_copy_line(std::string_view);
744 void PQXX_PRIVATE end_copy_write();
746 friend class internal::gate::connection_largeobject;
747 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
749 friend class internal::gate::connection_notification_receiver;
753 friend class internal::gate::connection_pipeline;
754 void PQXX_PRIVATE start_exec(
char const query[]);
755 bool PQXX_PRIVATE consume_input() noexcept;
756 bool PQXX_PRIVATE is_busy() const noexcept;
757 internal::pq::PGresult *get_result();
759 friend class internal::gate::connection_dbtransaction;
760 friend class internal::gate::connection_sql_cursor;
762 result exec_params(std::string_view query, internal::params const &args);
765 internal::pq::PGconn *m_conn =
nullptr;
779 using receiver_list =
782 receiver_list m_receivers;
793 template<typename T> inline std::
string connection::quote(T const &t)
const
809 std::string buf{
'\''};
810 buf.resize(2 + 2 * std::size(text) + 1);
811 auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
812 auto const closing_quote{1 + content_bytes};
813 buf[closing_quote] =
'\'';
814 auto const end{closing_quote + 1};
821 #if defined(PQXX_HAVE_CONCEPTS)
822 template<
internal::ZKey_ZValues MAPPING>
827 std::vector<char const *> keys, values;
828 if constexpr (std::ranges::sized_range<MAPPING>)
830 auto const size{std::ranges::size(params) + 1};
832 values.reserve(size);
834 for (
auto const &[key, value] : params)
839 keys.push_back(
nullptr);
840 values.push_back(
nullptr);
841 init(keys.data(), values.data());
843 #endif // PQXX_HAVE_CONCEPTS
849 PQXX_LIBEXPORT
void wait_read(internal::pq::PGconn
const *);
851 internal::pq::PGconn
const *, std::time_t seconds,
long microseconds);
852 PQXX_LIBEXPORT
void wait_write(internal::pq::PGconn
const *);
855 #include "pqxx/internal/compiler-internal-post.hxx"
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:555
std::string esc_raw(unsigned char const bin[], std::size_t len) const
Escape binary string for use as SQL string literal on this connection.
Definition: connection.cxx:821
std::string get_variable(std::string_view)
Read session variable, using SQL's SHOW command.
Definition: connection.cxx:245
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition: connection.cxx:95
Traits describing a type's "null value," if any.
Definition: strconv.hxx:87
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
void wait_write(internal::pq::PGconn const *)
Definition: connection.cxx:984
connection & operator=(connection const &)=delete
connection & operator=(connection &&rhs)
Move assignment.
Definition: connection.cxx:172
bool is_null(TYPE const &value) noexcept
Is value null?
Definition: strconv.hxx:331
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:579
connection()
Definition: connection.hxx:166
error_verbosity
Error verbosity levels.
Definition: connection.hxx:124
connection(connection const &)=delete
void trace(std::FILE *) noexcept
Enable tracing to a given output stream, or nullptr to disable.
Definition: connection.cxx:337
void unprepare(std::string_view name)
Drop prepared statement.
Definition: connection.cxx:623
Definition: connection.hxx:95
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:499
int PQXX_PURE protocol_version() const noexcept
What version of the PostgreSQL protocol is this connection using?
Definition: connection.cxx:226
encoding_group enc_group(int libpq_enc_id)
Definition: encodings.cxx:571
int PQXX_PURE sock() const noexcept
Socket currently used for connection, or -1 for none. Use with care!
Definition: connection.cxx:220
std::string encrypt_password(char const user[], char const password[], char const *algorithm=nullptr)
Encrypt a password for a given user.
Definition: connection.cxx:583
char const * dbname() const
Name of database we're connected to, if any.
Definition: connection.cxx:504
void unesc_bin(std::string_view escaped_data, std::byte buffer[])
Reconstitute binary data from its escaped version.
Definition: util.cxx:152
int PQXX_PURE server_version() const noexcept
What version of the PostgreSQL server are we connected to?
Definition: connection.cxx:232
std::string quote_raw(unsigned char const bin[], std::size_t len) const
Escape and quote a string of binary data.
Definition: connection.cxx:858
Database feature not supported in current setup.
Definition: except.hxx:207
int PQXX_PURE backendpid() const noexcept
Process ID for backend process, or 0 if inactive.
Definition: connection.cxx:205
void check_unique_register(void const *old_guest, std::string_view old_class, std::string_view old_name, void const *new_guest, std::string_view new_class, std::string_view new_name)
Check validity of registering a new "guest" in a "host.".
Definition: util.cxx:58
std::string const & channel() const
The channel that this receiver listens on.
Definition: notification.hxx:69
Internal items for libpqxx' own use. Do not use these yourself.
Definition: composite.hxx:74
void check_version()
Definition: util.hxx:167
int encoding_id() const
Get the connection's encoding, as a PostgreSQL-defined code.
Definition: connection.cxx:1071
char const * port() const
Server port number we're connected to.
Definition: connection.cxx:522
Invalid argument passed to libpqxx, similar to std::invalid_argument.
Definition: except.hxx:172
Connection to a database.
Definition: connection.hxx:164
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition: connection.hxx:793
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:57
void prepare(char const name[], char const definition[])
Define a prepared statement.
Definition: connection.cxx:607
void prepare(zview definition)
Definition: connection.hxx:524
Internal error in libpqxx library.
Definition: except.hxx:158
std::string_view name() const noexcept
Transaction name, if you passed one to the constructor; or empty string.
Definition: transaction_base.hxx:473
int get_notifs()
Check for pending notifications and take appropriate action.
Definition: connection.cxx:455
char const * username() const
Database user ID we're connected under, if any.
Definition: connection.cxx:510
Error in usage of libpqxx library, similar to std::logic_error.
Definition: except.hxx:165
std::string adorn_name(std::string_view)
Suffix unique number to name to make it unique within session context.
Definition: connection.cxx:1027
void cancel_query()
Attempt to cancel the ongoing query, if any.
Definition: connection.cxx:419
constexpr char const * as_c_string(char const str[]) noexcept
Get a raw C string pointer.
Definition: zview.hxx:112
Exception class for lost or failed backend connection.
Definition: except.hxx:68
char const * hostname() const
Address of server, or nullptr if none specified (i.e. default or local)
Definition: connection.cxx:516
std::string quote_name(std::string_view identifier) const
Escape and quote an SQL identifier for use in a query.
Definition: connection.cxx:883
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:549
void set_variable(std::string_view var, std::string_view value)
Set session variable, using SQL's SET command.
Definition: connection.cxx:238
PQXX_PURE char const * name_encoding(int encoding_id)
Definition: encodings.cxx:565
void set_verbosity(error_verbosity verbosity) noexcept
Set session verbosity.
Definition: connection.cxx:435
std::vector< errorhandler * > get_errorhandlers() const
Return pointers to the active errorhandlers.
Definition: connection.cxx:562
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:72
connection(zview options)
Definition: connection.hxx:174
void prepare(zview name, zview definition)
Definition: connection.hxx:510
bool PQXX_PURE is_open() const noexcept
Is this connection open at the moment?
Definition: connection.cxx:281
~connection()
Definition: connection.hxx:208
void process_notice(char const[]) noexcept
Invoke notice processor function. The message should end in newline.
Definition: connection.cxx:298
void set_client_encoding(zview encoding)
Set client-side character encoding, by name.
Definition: connection.hxx:338
std::string get_client_encoding() const
Get client-side character encoding, by name.
Definition: connection.cxx:1046
std::string describe_object(std::string_view class_name, std::string_view name)
Describe an object for humans, based on class name and optional name.
Definition: util.cxx:48
void wait_read(internal::pq::PGconn const *)
Definition: connection.cxx:965
value_type const * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:120
connection(char const options[])
Definition: connection.hxx:168
void close()
Explicitly close the connection.
Definition: connection.cxx:644
Run-time failure encountered by libpqxx, similar to std::runtime_error.
Definition: except.hxx:43
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:38
std::string encrypt_password(zview user, zview password, zview algorithm)
Definition: connection.hxx:453
constexpr char const * c_str() const noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:76
Base class for error-handler callbacks.
Definition: errorhandler.hxx:53
void esc_bin(std::string_view binary_data, char buffer[]) noexcept
Hex-escape binary data into a buffer.
Definition: util.cxx:122
void check_unique_unregister(void const *old_guest, std::string_view old_class, std::string_view old_name, void const *new_guest, std::string_view new_class, std::string_view new_name)
Like check_unique_register, but for un-registering a guest.
Definition: util.cxx:75
int await_notification()
Wait for a notification to come in.
Definition: connection.cxx:1002
Exception class for failed queries.
Definition: except.hxx:79
Result set containing data returned by a query or command.
Definition: result.hxx:71
Definition: notification.hxx:56
std::string connection_string() const
Return a connection string encapsulating this connection's options.
Definition: connection.cxx:1132
std::string esc_like(std::string_view text, char escape_char='\\') const
Escape string for literal LIKE match.
Definition: connection.cxx:895