libpqxx
connection_base.hxx
1
13#ifndef PQXX_H_CONNECTION_BASE
14#define PQXX_H_CONNECTION_BASE
15
16#include "pqxx/compiler-public.hxx"
17#include "pqxx/compiler-internal-pre.hxx"
18
19#include <bitset>
20#include <list>
21#include <map>
22#include <memory>
23
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"
30
31
32/* Use of the libpqxx library starts here.
33 *
34 * Everything that can be done with a database through libpqxx must go through
35 * a connection object derived from connection_base.
36 */
37
38/* Methods tested in eg. self-test program test1 are marked with "//[t01]"
39 */
40
41namespace pqxx
42{
43namespace internal
44{
46class sql_cursor;
47
49{
50public:
52
53 void add(int n) noexcept { m_counter += n; }
54 void clear() noexcept { m_counter = 0; }
55 int get() const noexcept { return m_counter; }
56
57private:
58 int m_counter = 0;
59};
60
61}
62
63
65
81std::string PQXX_LIBEXPORT encrypt_password( //[t00]
82 const std::string &user,
83 const std::string &password);
84
85
86namespace internal
87{
88namespace gate
89{
90class connection_dbtransaction;
91class connection_errorhandler;
92class connection_largeobject;
93class connection_notification_receiver;
94class connection_parameterized_invocation;
95class connection_pipeline;
96class connection_prepare_invocation;
97class connection_reactivation_avoidance_exemption;
98class connection_sql_cursor;
99class connection_transaction;
100class const_connection_largeobject;
101} // namespace pqxx::internal::gate
102} // namespace pqxx::internal
103
104
106
139class PQXX_LIBEXPORT connection_base
140{
141public:
143 void disconnect() noexcept; //[t02]
144
146
150 bool PQXX_PURE is_open() const noexcept; //[t01]
151
168
178 PQXX_DEPRECATED void activate(); //[t12]
179
181
189 PQXX_DEPRECATED void deactivate(); //[t12]
190
192
236 PQXX_DEPRECATED void inhibit_reactivation(bool inhibit) //[t86]
237 { m_inhibit_reactivation=inhibit; }
238
240
245 void simulate_failure(); //[t94]
247
249 void process_notice(const char[]) noexcept; //[t14]
251 void process_notice(const std::string &) noexcept; //[t14]
252
254 void trace(std::FILE *) noexcept; //[t03]
255
265
268 const char *dbname(); //[t01]
269
271
274 const char *username(); //[t01]
275
277
280 const char *hostname(); //[t01]
281
283
286 const char *port(); //[t01]
287
289
298 int PQXX_PURE backendpid() const noexcept; //[t01]
299
301
316 int PQXX_PURE sock() const noexcept; //[t87]
317
326
328
332 {
335 };
336
337
339
355 bool supports(capability c) const noexcept //[t88]
356 { return m_caps.test(c); }
357
359
367 int PQXX_PURE protocol_version() const noexcept; //[t01]
368
370
382 int PQXX_PURE server_version() const noexcept; //[t01]
384
386
407 std::string get_client_encoding() const;
408
410
413 void set_client_encoding(const std::string &encoding); //[t07]
414
416
419 void set_client_encoding(const char encoding[]); //[t07]
420
422 int PQXX_PRIVATE encoding_id() const;
423
425
427
443 void set_variable( //[t60]
444 const std::string &Var,
445 const std::string &Value);
446
448
455 std::string get_variable(const std::string &); //[t60]
457
458
464
476 int get_notifs(); //[t04]
477
478
480
486 int await_notification(); //[t78]
487
489
495 int await_notification(long seconds, long microseconds); //[t79]
497
498
524
557 void prepare(const std::string &name, const std::string &definition);
558
560
566 void prepare(const std::string &definition);
567
569 void unprepare(const std::string &name);
570
572
582 void prepare_now(const std::string &name);
583
589
600 template<typename TRANSACTOR>
601 PQXX_DEPRECATED void perform(const TRANSACTOR &T, int Attempts); //[t04]
602
604
610 template<typename TRANSACTOR>
611 PQXX_DEPRECATED void perform(const TRANSACTOR &T)
612 {
613#include "pqxx/internal/ignore-deprecated-pre.hxx"
614 perform(T, 3);
615#include "pqxx/internal/ignore-deprecated-post.hxx"
616 }
617
619
622 std::string adorn_name(const std::string &); //[90]
623
629 std::string esc(const char str[]);
630
632 std::string esc(const char str[], size_t maxlen);
633
635 std::string esc(const std::string &str);
636
638 std::string esc_raw(const unsigned char str[], size_t len);
639
641
644 std::string unesc_raw(const std::string &text)
645 { return unesc_raw(text.c_str()); }
646
648
651 std::string unesc_raw(const char *text);
652
654 std::string quote_raw(const unsigned char str[], size_t len);
655
657 std::string quote_name(const std::string &identifier);
658
660
661 template<typename T>
662 std::string quote(const T &t)
663 {
664 if (string_traits<T>::is_null(t)) return "NULL";
665 return "'" + this->esc(to_string(t)) + "'";
666 }
667
668 std::string quote(const binarystring &);
669
671
694 std::string esc_like(const std::string &str, char escape_char='\\') const;
696
698 void cancel_query();
699
702 {
703 // These values must match those in libpq's PGVerbosity enum.
704 terse=0,
705 normal=1,
706 verbose=2
707 };
708
710
718 void set_verbosity(error_verbosity verbosity) noexcept;
720 error_verbosity get_verbosity() const noexcept {return m_verbosity;}
721
723
735 std::vector<errorhandler *> get_errorhandlers() const;
736
737protected:
739 m_policy{pol}
740 {
741 // Check library version. The check_library_version template is declared
742 // for any library version, but only actually defined for the version of
743 // the libpqxx binary against which the code is linked.
744 //
745 // If the library binary is a different version than the one declared in
746 // these headers, then this call will fail to link: there will be no
747 // definition for the function with these exact template parameter values.
748 // There will be a definition, but the version in the parameter values will
749 // be different.
750 //
751 // There is no particular reason to do this here in this constructor, except
752 // to ensure that every meaningful libpqxx client will execute it. The call
753 // must be in the execution path somewhere or the compiler won't try to link
754 // it. We can't use it to initialise a global or class-static variable,
755 // because a smart compiler might resolve it at compile time.
756 //
757 // On the other hand, we don't want to make a useless function call too
758 // often for performance reasons. A local static variable is initialised
759 // only on the definition's first execution. Compilers will be well
760 // optimised for this behaviour, so there's a minimal one-time cost.
761 static const auto version_ok =
763 ignore_unused(version_ok);
764
765 clearcaps();
766 }
767 void init();
768
769 void close() noexcept;
770 void wait_read() const;
771 void wait_read(long seconds, long microseconds) const;
772 void wait_write() const;
773
774private:
775
776 result make_result(internal::pq::PGresult *rhs, const std::string &query);
777
778 void clearcaps() noexcept;
779 void PQXX_PRIVATE set_up_state();
780 void PQXX_PRIVATE check_result(const result &);
781
782 void PQXX_PRIVATE internal_set_trace() noexcept;
783 int PQXX_PRIVATE PQXX_PURE status() const noexcept;
784
785 friend class internal::gate::const_connection_largeobject;
786 const char * PQXX_PURE err_msg() const noexcept;
787
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;
791
792 void read_capabilities();
793
794 prepare::internal::prepared_def &find_prepared(const std::string &);
795
796 prepare::internal::prepared_def &register_prepared(const std::string &);
797
798 friend class internal::gate::connection_prepare_invocation;
800 PQXX_DEPRECATED result prepared_exec(
801 const std::string &,
802 const char *const[],
803 const int[],
804 const int[],
805 int);
806 result exec_prepared(const std::string &statement, const internal::params &);
807 bool prepared_exists(const std::string &) const;
808
810 internal::pq::PGconn *m_conn = nullptr;
811
812 connectionpolicy &m_policy;
813
815 internal::unique<transaction_base> m_trans;
816
818 void set_notice_processor();
820 void clear_notice_processor();
821 std::list<errorhandler *> m_errorhandlers;
822
824 std::FILE *m_trace = nullptr;
825
826 using receiver_list =
827 std::multimap<std::string, pqxx::notification_receiver *>;
829 receiver_list m_receivers;
830
832 std::map<std::string, std::string> m_vars;
833
834 using PSMap = std::map<std::string, prepare::internal::prepared_def>;
836 PSMap m_prepared;
837
839 int m_serverversion = 0;
840
842 internal::reactivation_avoidance_counter m_reactivation_avoidance;
843
845 int m_unique_id = 0;
846
848 bool m_completed = false;
849
851 bool m_inhibit_reactivation = false;
852
854 std::bitset<cap_end> m_caps;
855
857 error_verbosity m_verbosity = normal;
858
859 friend class internal::gate::connection_errorhandler;
860 void PQXX_PRIVATE register_errorhandler(errorhandler *);
861 void PQXX_PRIVATE unregister_errorhandler(errorhandler *) noexcept;
862
863 friend class internal::gate::connection_transaction;
864 result PQXX_PRIVATE exec(const char[], int Retries);
865 void PQXX_PRIVATE register_transaction(transaction_base *);
866 void PQXX_PRIVATE unregister_transaction(transaction_base *) noexcept;
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> &);
872
873 friend class internal::gate::connection_largeobject;
874 internal::pq::PGconn *raw_connection() const { return m_conn; }
875
876 friend class internal::gate::connection_notification_receiver;
877 void add_receiver(notification_receiver *);
878 void remove_receiver(notification_receiver *) noexcept;
879
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();
885
886 friend class internal::gate::connection_dbtransaction;
887
888 friend class internal::gate::connection_sql_cursor;
889 void add_reactivation_avoidance_count(int);
890
891 friend class internal::gate::connection_reactivation_avoidance_exemption;
892
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[],
900 int nparams);
901
902 result exec_params(
903 const std::string &query,
904 const internal::params &args);
905
906 connection_base(const connection_base &) =delete;
907 connection_base &operator=(const connection_base &) =delete;
908};
909
910
911namespace internal
912{
913
916{
917public:
920
921 void close_connection() noexcept { m_open = false; }
922
923private:
924 connection_base &m_home;
925 int m_count;
926 bool m_open;
927};
928
929
930void wait_read(const internal::pq::PGconn *);
931void wait_read(const internal::pq::PGconn *, long seconds, long microseconds);
932void wait_write(const internal::pq::PGconn *);
933} // namespace pqxx::internal
934
935} // namespace pqxx
936
937#include "pqxx/compiler-internal-post.hxx"
938
939#endif
STL namespace.
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
std::string to_string(const field &Obj)
Convert a field to a string.
Definition: result.cxx:451
auto perform(const TRANSACTION_CALLBACK &callback, int attempts=3) -> decltype(callback())
Simple way to execute a transaction with automatic retry.
Definition: transactor.hxx:99
void ignore_unused(T)
Suppress compiler warning about an unused item.
Definition: util.hxx:38
std::string encrypt_password(const std::string &user, const std::string &password)
Encrypt password for given user.
Definition: connection_base.cxx:89
int check_library_version< PQXX_VERSION_MAJOR, PQXX_VERSION_MINOR >() noexcept
Definition: version.cxx:13
Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.
Definition: binarystring.hxx:54
Definition: connection_base.hxx:49
int get() const noexcept
Definition: connection_base.hxx:55
void clear() noexcept
Definition: connection_base.hxx:54
void add(int n) noexcept
Definition: connection_base.hxx:53
connection_base abstract base class; represents a connection to a database.
Definition: connection_base.hxx:140
connection_base(connectionpolicy &pol)
Definition: connection_base.hxx:738
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
capability
Session capabilities.
Definition: connection_base.hxx:332
@ cap_end
Not a capability value; end-of-enumeration marker.
Definition: connection_base.hxx:334
error_verbosity get_verbosity() const noexcept
Retrieve current error verbosity.
Definition: connection_base.hxx:720
std::string quote(const T &t)
Represent object as SQL string, including quoting & escaping.
Definition: connection_base.hxx:662
error_verbosity
Error verbosity levels.
Definition: connection_base.hxx:702
void inhibit_reactivation(bool inhibit)
Definition: connection_base.hxx:236
bool supports(capability c) const noexcept
Does this connection seem to support the given capability?
Definition: connection_base.hxx:355
Scoped exemption to reactivation avoidance.
Definition: connection_base.hxx:916
void close_connection() noexcept
Definition: connection_base.hxx:921
Definition: connectionpolicy.hxx:32
Base class for error-handler callbacks.
Definition: errorhandler.hxx:55
Definition: notification.hxx:56
Result set containing data returned by a query or command.
Definition: result.hxx:70
Traits class for use in string conversions.
Definition: strconv.hxx:51
Interface definition (and common code) for "transaction" classes.
Definition: transaction_base.hxx:138