13 #ifndef PQXX_H_CONNECTION_BASE
14 #define PQXX_H_CONNECTION_BASE
16 #include "pqxx/compiler-public.hxx"
17 #include "pqxx/compiler-internal-pre.hxx"
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/version.hxx"
53 void add(
int n) noexcept { m_counter += n; }
54 void clear() noexcept { m_counter = 0; }
55 int get() const noexcept {
return m_counter; }
82 const std::string &user,
83 const std::string &password);
90 class connection_dbtransaction;
91 class connection_errorhandler;
92 class connection_largeobject;
93 class connection_notification_receiver;
94 class connection_parameterized_invocation;
95 class connection_pipeline;
96 class connection_prepare_invocation;
97 class connection_reactivation_avoidance_exemption;
98 class connection_sql_cursor;
99 class connection_transaction;
100 class const_connection_largeobject;
143 void disconnect() noexcept;
150 bool PQXX_PURE is_open()
const noexcept;
178 PQXX_DEPRECATED
void activate();
189 PQXX_DEPRECATED
void deactivate();
237 { m_inhibit_reactivation=inhibit; }
245 void simulate_failure();
249 void process_notice(
const char[]) noexcept;
251 void process_notice(
const std::string &) noexcept;
254 void trace(std::FILE *) noexcept;
268 const char *dbname();
274 const char *username();
280 const char *hostname();
298 int PQXX_PURE backendpid() const noexcept;
316 int PQXX_PURE sock() const noexcept;
356 {
return m_caps.test(c); }
367 int PQXX_PURE protocol_version() const noexcept;
382 int PQXX_PURE server_version() const noexcept;
406 std::
string get_client_encoding() const;
413 void set_client_encoding(const std::
string &encoding);
419 void set_client_encoding(const
char encoding[]);
422 int PQXX_PRIVATE encoding_id() const;
444 const std::
string &Var,
445 const std::
string &Value);
455 std::
string get_variable(const std::
string &);
486 int await_notification();
495 int await_notification(
long seconds,
long microseconds);
557 void prepare(const std::
string &name, const std::
string &definition);
566 void prepare(const std::
string &definition);
569 void unprepare(const std::
string &name);
582 void prepare_now(const std::
string &name);
600 template<typename TRANSACTOR>
601 PQXX_DEPRECATED
void perform(const TRANSACTOR &T,
int Attempts);
610 template<typename TRANSACTOR>
611 PQXX_DEPRECATED
void perform(const TRANSACTOR &T)
613 #include "pqxx/internal/ignore-deprecated-pre.hxx"
615 #include "pqxx/internal/ignore-deprecated-post.hxx"
622 std::string adorn_name(
const std::string &);
628 std::string esc(
const char str[]);
632 std::string esc(
const char str[],
size_t maxlen);
635 std::string esc(
const std::string &str);
638 std::string esc_raw(
const unsigned char str[],
size_t len);
645 {
return unesc_raw(text.c_str()); }
651 std::string unesc_raw(
const char *text);
654 std::string quote_raw(
const unsigned char str[],
size_t len);
657 std::string quote_name(
const std::string &identifier);
665 return "'" + this->esc(
to_string(t)) +
"'";
694 std::string esc_like(
const std::string &str,
char escape_char=
'\\')
const;
718 void set_verbosity(error_verbosity verbosity) noexcept;
735 std::vector<errorhandler *> get_errorhandlers()
const;
761 static const auto version_ok =
769 void close() noexcept;
770 void wait_read() const;
771 void wait_read(
long seconds,
long microseconds) const;
772 void wait_write() const;
776 result make_result(internal::pq::PGresult *rhs, const std::
string &query);
778 void clearcaps() noexcept;
779 void PQXX_PRIVATE set_up_state();
780 void PQXX_PRIVATE check_result(const result &);
782 void PQXX_PRIVATE internal_set_trace() noexcept;
783 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
785 friend class internal::gate::const_connection_largeobject;
786 const
char * PQXX_PURE err_msg() const noexcept;
788 void PQXX_PRIVATE reset();
789 std::
string PQXX_PRIVATE raw_get_var(const std::
string &);
790 void PQXX_PRIVATE process_notice_raw(const
char msg[]) noexcept;
792 void read_capabilities();
794 prepare::internal::prepared_def &find_prepared(const std::
string &);
796 prepare::internal::prepared_def ®ister_prepared(const std::
string &);
798 friend class internal::gate::connection_prepare_invocation;
800 PQXX_DEPRECATED
result prepared_exec(
806 result exec_prepared(const std::
string &statement, const internal::params &);
807 bool prepared_exists(const std::
string &) const;
810 internal::pq::PGconn *m_conn =
nullptr;
818 void set_notice_processor();
820 void clear_notice_processor();
824 std::FILE *m_trace =
nullptr;
826 using receiver_list =
829 receiver_list m_receivers;
832 std::map<std::
string, std::
string> m_vars;
834 using PSMap = std::map<std::
string, prepare::internal::prepared_def>;
839 int m_serverversion = 0;
842 internal::reactivation_avoidance_counter m_reactivation_avoidance;
848 bool m_completed = false;
851 bool m_inhibit_reactivation = false;
854 std::bitset<cap_end> m_caps;
859 friend class internal::gate::connection_errorhandler;
860 void PQXX_PRIVATE register_errorhandler(
errorhandler *);
861 void PQXX_PRIVATE unregister_errorhandler(
errorhandler *) noexcept;
863 friend class internal::gate::connection_transaction;
864 result PQXX_PRIVATE exec(const
char[],
int Retries);
867 bool PQXX_PRIVATE read_copy_line(std::
string &);
868 void PQXX_PRIVATE write_copy_line(const std::
string &);
869 void PQXX_PRIVATE end_copy_write();
870 void PQXX_PRIVATE raw_set_var(const std::
string &, const std::
string &);
871 void PQXX_PRIVATE add_variables(const std::map<std::
string, std::
string> &);
873 friend class internal::gate::connection_largeobject;
874 internal::pq::PGconn *raw_connection()
const {
return m_conn; }
876 friend class internal::gate::connection_notification_receiver;
880 friend class internal::gate::connection_pipeline;
881 void PQXX_PRIVATE start_exec(
const std::string &);
882 bool PQXX_PRIVATE consume_input() noexcept;
883 bool PQXX_PRIVATE is_busy() const noexcept;
884 internal::pq::PGresult *get_result();
886 friend class internal::gate::connection_dbtransaction;
888 friend class internal::gate::connection_sql_cursor;
889 void add_reactivation_avoidance_count(
int);
891 friend class internal::gate::connection_reactivation_avoidance_exemption;
893 friend class internal::gate::connection_parameterized_invocation;
895 PQXX_DEPRECATED
result parameterized_exec(
896 const std::
string &query,
897 const
char *const params[],
898 const
int paramlengths[],
899 const
int binaries[],
903 const std::
string &query,
904 const internal::params &args);
930 void wait_read(
const internal::pq::PGconn *);
931 void wait_read(
const internal::pq::PGconn *,
long seconds,
long microseconds);
932 void wait_write(
const internal::pq::PGconn *);
937 #include "pqxx/compiler-internal-post.hxx"
int encoding_id() const
Get the connection's encoding, as a PostgreSQL-defined code.
Definition: connection_base.cxx:1417
bool supports(capability c) const noexcept
Does this connection seem to support the given capability?
Definition: connection_base.hxx:355
int PQXX_PURE server_version() const noexcept
What version of the PostgreSQL server are we connected to?
Definition: connection_base.cxx:218
capability
Session capabilities.
Definition: connection_base.hxx:331
void inhibit_reactivation(bool inhibit)
Definition: connection_base.hxx:236
void prepare_now(const std::string &name)
Request that prepared statement be registered with the server.
Definition: connection_base.cxx:810
std::string adorn_name(const std::string &)
Suffix unique number to name to make it unique within session context.
Definition: connection_base.cxx:1380
Private namespace for libpqxx's internal use; do not access.
Definition: connection_base.hxx:43
int PQXX_PURE backendpid() const noexcept
Process ID for backend process.
Definition: connection_base.cxx:119
void disconnect() noexcept
Explicitly close connection.
Definition: connection_base.cxx:344
void close_connection() noexcept
Definition: connection_base.hxx:921
void set_variable(const std::string &Var, const std::string &Value)
Set session variable.
Definition: connection_base.cxx:224
const char * username()
Database user ID we're connected under, if any.
Definition: connection_base.cxx:631
void process_notice(const char[]) noexcept
Invoke notice processor function. The message should end in newline.
Definition: connection_base.cxx:369
void unprepare(const std::string &name)
Drop prepared statement.
Definition: connection_base.cxx:763
const char * port()
Server port number we're connected to.
Definition: connection_base.cxx:649
connection_base(connectionpolicy &pol)
Definition: connection_base.hxx:738
void add(int n) noexcept
Definition: connection_base.hxx:53
std::vector< errorhandler * > get_errorhandlers() const
Return pointers to the active errorhandlers.
Definition: connection_base.cxx:702
void activate()
Definition: connection_base.cxx:140
void deactivate()
Definition: connection_base.cxx:178
Run-time failure encountered by libpqxx, similar to std::runtime_error.
Definition: except.hxx:89
void close() noexcept
Definition: connection_base.cxx:902
Result set containing data returned by a query or command.
Definition: result.hxx:69
std::string encrypt_password(const std::string &user, const std::string &password)
Encrypt password for given user.
Definition: connection_base.cxx:89
error_verbosity get_verbosity() const noexcept
Retrieve current error verbosity.
Definition: connection_base.hxx:720
std::string esc_like(const std::string &str, char escape_char='\\') const
Escape string for literal LIKE match.
Definition: connection_base.cxx:1186
std::string quote_name(const std::string &identifier)
Escape and quote an SQL identifier for use in a query.
Definition: connection_base.cxx:1171
const std::string & channel() const
The channel that this receiver listens on.
Definition: notification.hxx:69
int get_notifs()
Check for pending notifications and take appropriate action.
Definition: connection_base.cxx:570
void ignore_unused(T)
Suppress compiler warning about an unused item.
Definition: util.hxx:38
void prepare(const std::string &name, const std::string &definition)
Define a prepared statement.
Definition: connection_base.cxx:731
const char * name_encoding(int encoding_id)
Definition: encodings.cxx:631
@ cap_end
Not a capability value; end-of-enumeration marker.
Definition: connection_base.hxx:334
Exception class for failed queries.
Definition: except.hxx:130
Definition: notification.hxx:55
Definition: connection_base.hxx:48
void wait_write() const
Definition: connection_base.cxx:1322
encoding_group enc_group(int libpq_enc_id)
Definition: encodings.cxx:637
std::string esc(const char str[])
Escape string for use as SQL string literal on this connection.
Definition: connection_base.cxx:1114
const char * dbname()
Name of database we're connected to, if any.
Definition: connection_base.cxx:622
void trace(std::FILE *) noexcept
Enable tracing to a given output stream, or nullptr to disable.
Definition: connection_base.cxx:430
void wait_write(const internal::pq::PGconn *)
Definition: connection_base.cxx:1304
reactivation_avoidance_counter()=default
Base class for error-handler callbacks.
Definition: errorhandler.hxx:54
size_type size() const noexcept
Size of converted string in bytes.
Definition: binarystring.hxx:80
std::string get_client_encoding() const
Get client-side character encoding, by name.
Definition: connection_base.cxx:1387
void init()
Definition: connection_base.cxx:99
Internal error in libpqxx library.
Definition: except.hxx:207
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:53
Exception class for lost or failed backend connection.
Definition: except.hxx:118
error_verbosity
Error verbosity levels.
Definition: connection_base.hxx:701
std::string unesc_raw(const std::string &text)
Unescape binary data, e.g. from a table field or notification payload.
Definition: connection_base.hxx:644
Dedicated namespace for helper types related to prepared statements.
Definition: prepared_statement.hxx:25
void cancel_query()
Attempt to cancel the ongoing query, if any.
Definition: connection_base.cxx:542
int await_notification()
Wait for a notification to come in.
Definition: connection_base.cxx:1328
std::string esc_raw(const unsigned char str[], size_t len)
Escape binary string for use as SQL string literal on this connection.
Definition: connection_base.cxx:1126
~reactivation_avoidance_exemption()
Definition: connection_base.cxx:1220
void simulate_failure()
Make the connection fail.
Definition: connection_base.cxx:200
int get() const noexcept
Definition: connection_base.hxx:55
Scoped exemption to reactivation avoidance.
Definition: connection_base.hxx:915
std::string quote(const T &t)
Represent object as SQL string, including quoting & escaping.
Definition: connection_base.hxx:662
void wait_read(const internal::pq::PGconn *)
Definition: connection_base.cxx:1284
int PQXX_PURE protocol_version() const noexcept
What version of the PostgreSQL protocol is this connection using?
Definition: connection_base.cxx:212
void freepqmem(const void *) noexcept
Definition: util.cxx:106
const char * hostname()
Address of server, or nullptr if none specified (i.e. default or local)
Definition: connection_base.cxx:640
auto perform(const TRANSACTION_CALLBACK &callback, int attempts=3) -> decltype(callback())
Simple way to execute a transaction with automatic retry.
Definition: transactor.hxx:99
bool PQXX_PURE is_open() const noexcept
Is this connection open at the moment?
Definition: connection_base.cxx:353
Invalid argument passed to libpqxx, similar to std::invalid_argument.
Definition: except.hxx:229
std::string to_string(const field &Obj)
Convert a field to a string.
Definition: result.cxx:451
void set_verbosity(error_verbosity verbosity) noexcept
Set session verbosity.
Definition: connection_base.cxx:549
Database feature not supported in current setup.
Definition: except.hxx:272
connection_base abstract base class; represents a connection to a database.
Definition: connection_base.hxx:139
int PQXX_PURE sock() const noexcept
Socket currently used for connection, or -1 for none. Use with care!
Definition: connection_base.cxx:134
std::string quote_raw(const unsigned char str[], size_t len)
Escape and quote a string of binary data.
Definition: connection_base.cxx:1157
void set_client_encoding(const std::string &encoding)
Set client-side character encoding, by name.
Definition: connection_base.cxx:1411
Internal representation of a prepared statement definition.
Definition: prepared_statement.hxx:156
Traits class for use in string conversions.
Definition: strconv.hxx:51
std::string get_variable(const std::string &)
Read session variable.
Definition: connection_base.cxx:241
reactivation_avoidance_exemption(connection_base &C)
Definition: connection_base.cxx:1208
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:136
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:25
Error in usage of libpqxx library, similar to std::logic_error.
Definition: except.hxx:218
const value_type * data() const noexcept
Unescaped field contents.
Definition: binarystring.hxx:102
Definition: connectionpolicy.hxx:31
void wait_read() const
Definition: connection_base.cxx:1310
int check_library_version< PQXX_VERSION_MAJOR, PQXX_VERSION_MINOR >() noexcept
Definition: version.cxx:13
void clear() noexcept
Definition: connection_base.hxx:54