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 <string_view>
24 #include "pqxx/errorhandler.hxx"
25 #include "pqxx/except.hxx"
26 #include "pqxx/prepared_statement.hxx"
27 #include "pqxx/strconv.hxx"
28 #include "pqxx/util.hxx"
29 #include "pqxx/zview.hxx"
67 class connection_dbtransaction;
68 class connection_errorhandler;
69 class connection_largeobject;
70 class connection_notification_receiver;
71 class connection_pipeline;
72 class connection_sql_cursor;
73 class connection_stream_from;
74 class connection_stream_to;
75 class connection_transaction;
76 class const_connection_largeobject;
83 [[nodiscard]] std::string PQXX_LIBEXPORT
87 [[nodiscard]]
inline std::string
157 connection(connection &&rhs);
165 catch (std::exception
const &)
183 [[nodiscard]]
bool PQXX_PURE is_open() const noexcept;
186 void process_notice(
char const[]) noexcept;
188 void process_notice(std::
string const &msg) noexcept
190 process_notice(
zview{msg});
196 void process_notice(
zview) noexcept;
199 void trace(std::FILE *) noexcept;
211 [[nodiscard]]
char const *dbname()
const;
215 [[nodiscard]]
char const *username()
const;
218 [[nodiscard]]
char const *hostname()
const;
221 [[nodiscard]]
char const *port()
const;
224 [[nodiscard]]
int PQXX_PURE backendpid() const noexcept;
242 [[nodiscard]]
int PQXX_PURE sock() const noexcept;
248 [[nodiscard]]
int PQXX_PURE protocol_version() const noexcept;
263 [[nodiscard]]
int PQXX_PURE server_version() const noexcept;
287 [[nodiscard]] std::
string get_client_encoding() const;
294 void set_client_encoding(std::
string const &encoding)
296 set_client_encoding(encoding.c_str());
303 void set_client_encoding(
char const encoding[]);
306 [[nodiscard]]
int PQXX_PRIVATE encoding_id()
const;
326 void set_variable(std::string_view var, std::string_view value);
332 std::string get_variable(std::string_view);
365 int await_notification();
376 int await_notification(
long seconds,
long microseconds);
407 char const user[],
char const password[],
char const *algorithm =
nullptr);
408 [[nodiscard]] std::string
464 void prepare(
char const name[],
char const definition[]);
466 void prepare(std::string
const &name, std::string
const &definition)
468 prepare(name.c_str(), definition.c_str());
484 void prepare(
char const definition[]);
488 void unprepare(std::string_view name);
498 [[nodiscard]] std::string adorn_name(std::string_view);
510 [[nodiscard]] std::string
esc(
char const text[],
size_t maxlen)
const
512 return esc(std::string_view(text, maxlen));
516 [[nodiscard]] std::string
esc(
char const text[])
const
518 return esc(std::string_view(text));
525 [[nodiscard]] std::string esc(std::string_view text)
const;
528 [[nodiscard]] std::string
529 esc_raw(
unsigned char const bin[],
size_t len)
const;
535 [[nodiscard]] std::string
unesc_raw(std::string
const &text)
const
537 return unesc_raw(text.c_str());
546 return unesc_raw(text.
c_str());
553 [[nodiscard]] std::string unesc_raw(
char const text[])
const;
556 [[nodiscard]] std::string
557 quote_raw(
unsigned char const bin[],
size_t len)
const;
560 [[nodiscard]] std::string quote_name(std::string_view identifier)
const;
566 template<
typename T>[[nodiscard]]
inline std::string quote(T
const &t)
const;
568 [[nodiscard]] std::string quote(
binarystring const &)
const;
594 [[nodiscard]] std::string
595 esc_like(std::string_view text,
char escape_char =
'\\')
const;
630 [[nodiscard]] std::vector<errorhandler *> get_errorhandlers()
const;
639 [[nodiscard]] std::string connection_string()
const;
648 void init(
char const options[]);
650 void wait_read()
const;
651 void wait_read(
long seconds,
long microseconds)
const;
654 internal::pq::PGresult *pgr, std::shared_ptr<std::string>
const &query);
656 void PQXX_PRIVATE set_up_state();
658 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
665 size_t esc_to_buf(std::string_view text,
char *buf) const;
667 friend class internal::gate::const_connection_largeobject;
668 char const *PQXX_PURE err_msg() const noexcept;
670 void PQXX_PRIVATE process_notice_raw(
char const msg[]) noexcept;
672 result exec_prepared(std::string_view statement, internal::params const &);
675 void check_movable() const;
677 void check_overwritable() const;
679 friend class internal::gate::connection_errorhandler;
680 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
681 void PQXX_PRIVATE unregister_errorhandler(
errorhandler *) noexcept;
683 friend class internal::gate::connection_transaction;
684 result PQXX_PRIVATE exec(std::string_view);
685 result PQXX_PRIVATE exec(std::shared_ptr<std::
string>);
689 friend class internal::gate::connection_stream_from;
690 bool PQXX_PRIVATE read_copy_line(std::
string &);
692 friend class internal::gate::connection_stream_to;
693 void PQXX_PRIVATE write_copy_line(std::string_view);
694 void PQXX_PRIVATE end_copy_write();
696 friend class internal::gate::connection_largeobject;
697 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
699 friend class internal::gate::connection_notification_receiver;
703 friend class internal::gate::connection_pipeline;
704 void PQXX_PRIVATE start_exec(
char const query[]);
705 bool PQXX_PRIVATE consume_input() noexcept;
706 bool PQXX_PRIVATE is_busy() const noexcept;
707 internal::pq::PGresult *get_result();
709 friend class internal::gate::connection_dbtransaction;
710 friend class internal::gate::connection_sql_cursor;
712 result exec_params(std::string_view query, internal::params const &args);
715 internal::pq::PGconn *m_conn =
nullptr;
722 using receiver_list =
725 receiver_list m_receivers;
736 template<typename T> inline std::
string connection::quote(T const &t)
const
746 std::string buf{
'\''};
747 buf.resize(2 + 2 * text.size() + 1);
748 auto const content_bytes{esc_to_buf(text, buf.data() + 1)};
749 auto const closing_quote{1 + content_bytes};
750 buf[closing_quote] =
'\'';
751 auto const end{closing_quote + 1};
760 PQXX_LIBEXPORT
void wait_read(internal::pq::PGconn
const *);
762 wait_read(internal::pq::PGconn
const *,
long seconds,
long microseconds);
763 PQXX_LIBEXPORT
void wait_write(internal::pq::PGconn
const *);
766 #include "pqxx/internal/compiler-internal-post.hxx"
connection(char const options[])
Definition: connection.hxx:143
bool is_null(TYPE const &value)
Is value null?
Definition: strconv.hxx:286
const char * name_encoding(int encoding_id)
Definition: encodings.cxx:579
int PQXX_PURE sock() const noexcept
Socket currently used for connection, or -1 for none. Use with care!
Definition: connection.cxx:206
const char * username() const
Database user ID we're connected under, if any.
Definition: connection.cxx:502
std::string encrypt_password(char const user[], char const password[], char const *algorithm=nullptr)
Encrypt a password for a given user.
Definition: connection.cxx:575
std::string encrypt_password(char const user[], char const password[])
Encrypt a password.
Definition: connection.cxx:93
int PQXX_PURE server_version() const noexcept
What version of the PostgreSQL server are we connected to?
Definition: connection.cxx:218
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:25
int await_notification()
Wait for a notification to come in.
Definition: connection.cxx:947
void wait_write(internal::pq::PGconn const *)
Definition: connection.cxx:929
int encoding_id() const
Get the connection's encoding, as a PostgreSQL-defined code.
Definition: connection.cxx:1015
const std::string & channel() const
The channel that this receiver listens on.
Definition: notification.hxx:69
constexpr const char * c_str() const noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:41
error_verbosity
Error verbosity levels.
Definition: connection.hxx:95
Definition: connection.hxx:65
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:478
encoding_group enc_group(int libpq_enc_id)
Definition: encodings.cxx:585
const char * dbname() const
Name of database we're connected to, if any.
Definition: connection.cxx:496
void prepare(char const name[], char const definition[])
Define a prepared statement.
Definition: connection.cxx:599
void set_client_encoding(std::string const &encoding)
Set client-side character encoding, by name.
Definition: connection.hxx:294
Run-time failure encountered by libpqxx, similar to std::runtime_error.
Definition: except.hxx:42
connection & operator=(connection &&rhs)
Move assignment.
Definition: connection.cxx:158
Private namespace for libpqxx's internal use; do not access.
Definition: connection.hxx:59
void check_version()
Definition: util.hxx:136
std::string adorn_name(std::string_view)
Suffix unique number to name to make it unique within session context.
Definition: connection.cxx:971
connection()
Definition: connection.hxx:138
void cancel_query()
Attempt to cancel the ongoing query, if any.
Definition: connection.cxx:412
int PQXX_PURE protocol_version() const noexcept
What version of the PostgreSQL protocol is this connection using?
Definition: connection.cxx:212
std::string quote_name(std::string_view identifier) const
Escape and quote an SQL identifier for use in a query.
Definition: connection.cxx:827
Exception class for failed queries.
Definition: except.hxx:78
Result set containing data returned by a query or command.
Definition: result.hxx:70
void set_verbosity(error_verbosity verbosity) noexcept
Set session verbosity.
Definition: connection.cxx:427
const char * hostname() const
Address of server, or nullptr if none specified (i.e. default or local)
Definition: connection.cxx:508
Definition: notification.hxx:55
const char * port() const
Server port number we're connected to.
Definition: connection.cxx:514
int PQXX_PURE backendpid() const noexcept
Process ID for backend process, or 0 if inactive.
Definition: connection.cxx:191
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:97
connection(zview options)
Definition: connection.hxx:149
void prepare(zview name, zview definition)
Definition: connection.hxx:471
Exception class for lost or failed backend connection.
Definition: except.hxx:67
bool PQXX_PURE is_open() const noexcept
Is this connection open at the moment?
Definition: connection.cxx:274
Internal error in libpqxx library.
Definition: except.hxx:157
~connection()
Definition: connection.hxx:159
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:32
std::string quote(T const &t) const
Represent object as SQL string, including quoting & escaping.
Definition: connection.hxx:736
void prepare(zview definition)
Definition: connection.hxx:485
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:81
std::string esc_raw(unsigned char const bin[], size_t len) const
Escape binary string for use as SQL string literal on this connection.
Definition: connection.cxx:791
const value_type * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:109
void close()
Explicitly close the connection.
Definition: connection.cxx:635
int get_notifs()
Check for pending notifications and take appropriate action.
Definition: connection.cxx:447
std::string quote_raw(unsigned char const bin[], size_t len) const
Escape and quote a string of binary data.
Definition: connection.cxx:815
Database feature not supported in current setup.
Definition: except.hxx:206
std::string encrypt_password(zview user, zview password, zview algorithm)
Definition: connection.hxx:409
void set_variable(std::string_view var, std::string_view value)
Set session variable, using SQL's SET command.
Definition: connection.cxx:224
void wait_read(internal::pq::PGconn const *)
Definition: connection.cxx:909
std::vector< errorhandler * > get_errorhandlers() const
Return pointers to the active errorhandlers.
Definition: connection.cxx:554
Invalid argument passed to libpqxx, similar to std::invalid_argument.
Definition: except.hxx:171
Connection to a database.
Definition: connection.hxx:135
std::string connection_string() const
Return a connection string encapsulating this connection's options.
Definition: connection.cxx:1076
std::string esc_like(std::string_view text, char escape_char='\\') const
Escape string for literal LIKE match.
Definition: connection.cxx:839
std::string esc(char const text[]) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:516
connection(std::string const &options)
Definition: connection.hxx:140
std::string get_variable(std::string_view)
Read session variable, using SQL's SHOW command.
Definition: connection.cxx:236
std::string esc(char const text[], size_t maxlen) const
Escape string for use as SQL string literal on this connection.
Definition: connection.hxx:510
void process_notice(char const[]) noexcept
Invoke notice processor function. The message should end in newline.
Definition: connection.cxx:291
std::string unesc_raw(std::string const &text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:535
Error in usage of libpqxx library, similar to std::logic_error.
Definition: except.hxx:164
std::string get_client_encoding() const
Get client-side character encoding, by name.
Definition: connection.cxx:990
std::string unesc_raw(zview text) const
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection.hxx:544
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:53
void prepare(std::string const &name, std::string const &definition)
Definition: connection.hxx:466
void trace(std::FILE *) noexcept
Enable tracing to a given output stream, or nullptr to disable.
Definition: connection.cxx:330
Base class for error-handler callbacks.
Definition: errorhandler.hxx:52
void unprepare(std::string_view name)
Drop prepared statement.
Definition: connection.cxx:615