connection.hxx

Go to the documentation of this file.

/* Definition of the connection class.
 *
 * pqxx::connection encapsulates a connection to a database.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/connection instead.
 *
 * Copyright (c) 2000-2026, Jeroen T. Vermeulen.
 *
 * See COPYING for copyright license.  If you did not receive a file called
 * COPYING with this source code, please notify the distributor of this
 * mistake, or contact the author.
 */
#ifndef PQXX_CONNECTION_HXX
#define PQXX_CONNECTION_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <cstddef>
#include <ctime>
#include <format>
#include <functional>
#include <initializer_list>
#include <list>
#include <map>
#include <memory>
#include <ranges>
#include <string_view>
#include <tuple>
#include <utility>
 
#include "pqxx/errorhandler.hxx"
#include "pqxx/except.hxx"
#include "pqxx/internal/connection-string.hxx"
#include "pqxx/params.hxx"
#include "pqxx/result.hxx"
#include "pqxx/separated_list.hxx"
#include "pqxx/strconv.hxx"
#include "pqxx/types.hxx"
#include "pqxx/util.hxx"
#include "pqxx/zview.hxx"
 
 
namespace pqxx::internal
{
class sql_cursor;
 
 
 
PQXX_COLD PQXX_LIBEXPORT void skip_init_ssl(int skips) noexcept;
} // namespace pqxx::internal
 
 
namespace pqxx::internal::gate
{
class connection_dbtransaction;
class connection_errorhandler;
class connection_largeobject;
class connection_notification_receiver;
class connection_pipeline;
class connection_sql_cursor;
class connection_stream_from;
class connection_stream_to;
class connection_transaction;
class const_connection_largeobject;
} // namespace pqxx::internal::gate
 
 
namespace pqxx
{
 
template<typename T>
concept ZKey_ZValues = std::ranges::input_range<T> and requires(T t) {
  { std::get<0>(*std::cbegin(t)) } -> ZString;
  { std::get<1>(*std::cbegin(t)) } -> ZString;
  requires(
    std::tuple_size_v<std::remove_cvref_t<decltype(*std::cbegin(t))>> == 2u);
};
 
 
 
struct notification final
{
  // NOLINTBEGIN(cppcoreguidelines-avoid-const-or-ref-data-members)
 
 
  connection &conn;
 
  // NOLINTEND(cppcoreguidelines-avoid-const-or-ref-data-members)
 
 
  zview channel;
 
 
  zview payload;
 
 
  int backend_pid = 0;
};
 
 
 
enum skip_init : int
{
  nothing,
 
  openssl,
 
  crypto,
};
 
 
 
template<skip_init... SKIP> inline void skip_init_ssl() noexcept
{
  // (Normalise skip flags to one per.)
  pqxx::internal::skip_init_ssl(((1 << SKIP) | ...));
}
 
 
 
using table_path = std::initializer_list<std::string_view>;
 
 
enum class error_verbosity : int
{
  // These values must match those in libpq's PGVerbosity enum.
  terse = 0,
  normal = 1,
  verbose = 2
};
 
 
 
class PQXX_LIBEXPORT connection final
{
public:
  explicit connection(sl loc = sl::current()) :
          connection("", empty_params_t(), loc)
  {}
 
 
  template<pqxx::ZString STRING, ZKey_ZValues MAPPING>
  explicit inline connection(
    STRING const &connection_string, MAPPING &&params = empty_params_t(),
    sl = sl::current());
 
 
  template<pqxx::ZString STRING>
  explicit connection(
    STRING const &connection_string, sl loc = sl::current()) :
          connection{connection_string, empty_params_t(), loc}
  {}
 
  template<ZKey_ZValues MAPPING>
  explicit connection(MAPPING &&params, sl loc = sl::current()) :
          connection{"", params, loc}
  {}
 
 
  connection(connection &&rhs, sl = sl::current());
 
  ~connection()
  {
    try
    {
      close(m_created_loc);
    }
    catch (std::exception const &)
    {
      // TODO: Try to report the error.
    }
  }
 
  // TODO: Once we drop notification_receiver/errorhandler, move is easier.
 
  connection &operator=(connection &&rhs);
 
  connection(connection const &) = delete;
  connection &operator=(connection const &) = delete;
 
 
  [[nodiscard]] bool is_open() const noexcept;
 
  PQXX_ZARGS void process_notice(char const[]) noexcept;
 
  void process_notice(zview) noexcept;
 
  void trace(std::FILE *) noexcept;
 
 
  [[nodiscard]] char const *dbname() const noexcept;
 
 
  [[nodiscard]] char const *username() const noexcept;
 
 
  [[nodiscard]] PQXX_PURE char const *hostname() const noexcept;
 
  [[nodiscard, deprecated("Use port_number().")]] PQXX_PURE char const *
  port() const noexcept;
 
  [[nodiscard]] PQXX_PURE std::optional<int>
  port_number(sl loc = sl::current()) const;
 
  [[nodiscard]] PQXX_PURE int backendpid() const & noexcept;
 
 
  [[nodiscard]] PQXX_PURE int sock() const & noexcept;
 
 
  [[nodiscard]] PQXX_PURE int protocol_version() const noexcept;
 
 
  [[nodiscard]] PQXX_PURE int server_version() const noexcept;
 
 
  [[nodiscard]] std::string get_client_encoding(sl loc = sl::current()) const;
 
 
  void set_client_encoding(zview encoding, sl loc = sl::current()) &
  {
    set_client_encoding(encoding.c_str(), loc);
  }
 
 
  PQXX_ZARGS void
  set_client_encoding(char const encoding[], sl = sl::current()) &;
 
  [[nodiscard]] int encoding_id(sl = sl::current()) const;
 
  [[nodiscard]] encoding_group get_encoding_group(sl loc = sl::current()) const
  {
    return pqxx::internal::enc_group(this->encoding_id(loc), loc);
  }
 
 
 
  template<typename TYPE>
  void set_session_var(
    std::string_view var, TYPE const &value, sl loc = sl::current()) &
  {
    if constexpr (has_null<TYPE>())
    {
      if (is_null(value))
        throw variable_set_to_null{
          std::format("Attempted to set variable {} to null.", var), loc};
    }
    exec(std::format("SET {}={}", quote_name(var), quote(value, loc)), loc);
  }
 
 
  std::string get_var(std::string_view var, sl loc = sl::current());
 
 
  template<not_borrowed TYPE>
  TYPE get_var_as(std::string_view var, sl loc = sl::current())
  {
    conversion_context const c{get_encoding_group(), loc};
    return from_string<TYPE>(get_var(var, loc), c);
  }
 
 
  int get_notifs(sl = sl::current());
 
  // TODO: Unify with the other overload.
 
  int await_notification(sl = sl::current());
 
 
  int await_notification(
    std::time_t seconds = 10, long microseconds = 0, sl = sl::current());
 
 
  using notification_handler = std::function<void(notification)>;
 
 
  void listen(
    std::string_view channel, notification_handler handler = {},
    sl = sl::current());
 
 
  [[nodiscard]] std::string
  encrypt_password(zview user, zview password, zview algorithm)
  {
    return encrypt_password(user.c_str(), password.c_str(), algorithm.c_str());
  }
  [[nodiscard]] PQXX_ZARGS std::string encrypt_password(
    char const user[], char const password[], char const *algorithm = nullptr);
 
 
 
  void prepare(zview name, zview definition, sl loc = sl::current()) &
  {
    prepare(name.c_str(), definition.c_str(), loc);
  }
 
 
  void prepare(
    std::string const &name, std::string const &definition,
    sl loc = sl::current()) &
  {
    prepare(name.c_str(), definition.c_str(), loc);
  }
 
 
  PQXX_ZARGS void prepare(
    char const name[], char const definition[], sl loc = sl::current()) &;
 
 
  void prepare(
    std::string_view name, std::string_view definition,
    sl loc = sl::current()) &
  {
    std::string const n{name}, d{definition};
    prepare(n.c_str(), d.c_str(), loc);
  }
 
  [[deprecated("Either name your statement, or just parameterise it.")]]
  PQXX_ZARGS void prepare(char const definition[], sl loc = sl::current()) &;
  [[deprecated("Either name your statement, or just parameterise it.")]]
  void prepare(zview definition, sl loc = sl::current()) &
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    prepare(definition.c_str(), loc);
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
 
  void unprepare(std::string_view name, sl loc = sl::current());
 
 
 
  [[nodiscard]] std::string adorn_name(std::string_view);
 
 
  [[nodiscard]] PQXX_ZARGS std::string
  esc(char const text[], sl loc = sl::current()) const
  {
    return esc(std::string_view{text}, loc);
  }
 
 
  [[nodiscard]] std::string_view
  esc(std::string_view text, std::span<char> buffer, sl loc = sl::current())
  {
    auto const size{std::size(text)}, space{std::size(buffer)};
    auto const needed{2 * size + 1};
    if (space < needed)
      throw range_error{
        std::format(
          "Not enough room to escape string of {} byte(s): need {} bytes of "
          "buffer space, but buffer size is {}.",
          size, needed, size),
        loc};
    return {std::data(buffer), esc_to_buf(text, buffer, loc)};
  }
 
 
  [[nodiscard]] std::string
  esc(std::string_view text, sl loc = sl::current()) const;
 
 
  template<binary DATA> [[nodiscard]] std::string esc(DATA const &data) const
  {
    return esc_raw(data);
  }
 
 
  template<binary DATA>
  [[nodiscard]] zview
  esc(DATA const &data, std::span<char> buffer, sl loc = sl::current()) const
  {
    auto const size{std::size(data)}, space{std::size(buffer)};
    auto const needed{internal::size_esc_bin(std::size(data))};
    if (space < needed)
      throw range_error{
        std::format(
          "Not enough room to escape binary string of {} byte(s): need {} ",
          " bytes of buffer space, but buffer size is {}.", size, needed,
          space),
        loc};
 
    bytes_view const view{std::data(data), std::size(data)};
    // Actually, in the modern format, we know beforehand exactly how many
    // bytes we're going to fill.  Just leave out the trailing zero.
    internal::esc_bin(view, buffer);
    return zview{std::data(buffer), needed - 1};
  }
 
 
  [[nodiscard]] std::string esc_raw(bytes_view) const;
 
 
  template<binary DATA>
  [[nodiscard]] std::string esc_raw(DATA const &data) const
  {
    return esc_raw(bytes_view{std::data(data), std::size(data)});
  }
 
  template<binary DATA>
  [[nodiscard]] zview esc_raw(DATA const &data, std::span<char> buffer) const
  {
    return this->esc(binary_cast(data), buffer);
  }
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  [[nodiscard]] bytes
  unesc_bin(std::string_view text, sl loc = sl::current()) const
  {
    bytes buf{pqxx::internal::size_unesc_bin(std::size(text))};
    pqxx::internal::unesc_bin(text, buf, loc);
    return buf;
  }
 
 
  [[nodiscard]] std::string quote_raw(bytes_view) const;
 
 
  template<binary DATA>
  [[nodiscard]] std::string quote_raw(DATA const &data) const
  {
    return quote_raw(bytes_view{std::data(data), std::size(data)});
  }
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
  [[nodiscard]] std::string quote_name(std::string_view identifier) const;
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  [[nodiscard]] std::string quote_table(std::string_view name) const;
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  [[nodiscard]] std::string quote_table(table_path) const;
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  template<pqxx::char_strings STRINGS>
  inline std::string
  quote_columns(STRINGS const &columns, sl = sl::current()) const;
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  template<typename T>
  [[nodiscard]] inline std::string quote(T const &t, sl = sl::current()) const;
 
  // TODO: Make "into buffer" variant to eliminate a string allocation.
 
  [[nodiscard]] std::string esc_like(
    std::string_view text, char escape_char = '\\',
    sl loc = sl::current()) const;
 
 
  void cancel_query(sl = sl::current());
 
#if defined(_WIN32) || __has_include(<fcntl.h>)
 
  void set_blocking(bool block, sl = sl::current()) &;
#endif // defined(_WIN32) || __has_include(<fcntl.h>)
 
 
  void set_verbosity(error_verbosity verbosity) & noexcept;
 
 
  void set_notice_handler(std::function<void(zview)> handler)
  {
    m_notice_waiters->notice_handler = std::move(handler);
  }
 
 
  [[nodiscard, deprecated("Use a notice handler instead.")]]
  std::vector<errorhandler *> get_errorhandlers() const;
 
 
  [[nodiscard]] std::string connection_string() const;
 
 
  void close(sl = sl::current());
 
 
  static connection
  seize_raw_connection(internal::pq::PGconn *raw_conn, sl loc = sl::current())
  {
    return connection{raw_conn, loc};
  }
 
 
  internal::pq::PGconn *release_raw_connection() &&
  {
    return std::exchange(m_conn, nullptr);
  }
 
 
  [[deprecated("To set session variables, use set_session_var.")]] void
  set_variable(
    std::string_view var, std::string_view value, sl loc = sl::current()) &;
 
 
  [[deprecated("Use get_var instead.")]] std::string
  get_variable(std::string_view, sl loc = sl::current());
 
private:
  using empty_params_t =
    std::initializer_list<std::pair<char const *, char const *>>;
 
  friend class connecting;
  enum connect_mode
  {
    connect_nonblocking
  };
  connection(connect_mode, zview connection_string, sl);
 
  explicit connection(internal::pq::PGconn *raw_conn, sl);
 
 
  std::pair<bool, bool> poll_connect(sl);
 
  // Initialise based on connection string and key/value parameter pairs.
  void init(
    std::vector<const char *> const &override_keys,
    std::vector<const char *> const &override_values, sl);
 
  void set_up_notice_handlers();
 
  void complete_connection(sl);
 
  result make_result(
    internal::pq::PGresult *pgr, std::shared_ptr<std::string> const &query,
    std::string_view desc, sl = sl::current());
 
  result make_result(
    internal::pq::PGresult *pgr, std::shared_ptr<std::string> const &query,
    sl loc = sl::current())
  {
    return make_result(pgr, query, "", loc);
  }
 
  PQXX_PRIVATE [[nodiscard]] int status() const noexcept;
 
 
  [[nodiscard]] std::size_t
  esc_to_buf(std::string_view text, std::span<char> buf, sl loc) const;
 
  friend class internal::gate::const_connection_largeobject;
  [[nodiscard]] char const *err_msg() const noexcept;
 
  result exec_prepared(
    std::string_view statement, internal::c_params const &,
    sl loc = sl::current());
 
  void check_movable(sl) const;
  void check_overwritable(sl) const;
 
  friend class internal::gate::connection_errorhandler;
  PQXX_PRIVATE void register_errorhandler(errorhandler *);
  PQXX_PRIVATE void unregister_errorhandler(errorhandler *) noexcept;
 
  friend class internal::gate::connection_transaction;
  result exec(std::string_view query, sl loc) { return exec(query, "", loc); }
  result exec(std::string_view, std::string_view, sl);
  PQXX_PRIVATE result
  exec(std::shared_ptr<std::string> const &, std::string_view, sl);
  PQXX_PRIVATE result exec(std::shared_ptr<std::string> const &query, sl loc)
  {
    return exec(query, "", loc);
  }
 
  PQXX_PRIVATE void register_transaction(transaction_base *);
  PQXX_PRIVATE void unregister_transaction(transaction_base *) noexcept;
 
  friend class internal::gate::connection_stream_from;
 
  std::pair<std::unique_ptr<char[], void (*)(void const *)>, std::size_t>
    read_copy_line(sl);
 
  friend class internal::gate::connection_stream_to;
  PQXX_PRIVATE void write_copy_line(std::string_view, sl);
  PQXX_PRIVATE void end_copy_write(sl);
 
  friend class internal::gate::connection_largeobject;
  [[nodiscard]] constexpr internal::pq::PGconn *raw_connection() const noexcept
  {
    return m_conn;
  }
 
  friend class internal::gate::connection_notification_receiver;
  void add_receiver(notification_receiver *, sl);
  void remove_receiver(notification_receiver *, sl) noexcept;
 
  friend class internal::gate::connection_pipeline;
  PQXX_PRIVATE PQXX_ZARGS void start_exec(char const query[]);
  PQXX_PRIVATE bool consume_input() noexcept;
  PQXX_PRIVATE [[nodiscard]] bool is_busy() const noexcept;
  internal::pq::PGresult *get_result();
 
  friend class internal::gate::connection_dbtransaction;
  friend class internal::gate::connection_sql_cursor;
 
  result
  exec_params(std::string_view query, internal::c_params const &args, sl);
 
  internal::pq::PGconn *m_conn = nullptr;
 
 
  transaction_base const *m_trans = nullptr;
 
  std::shared_ptr<pqxx::internal::notice_waiters> m_notice_waiters;
 
  // TODO: Remove these when we retire notification_receiver.
  // TODO: Can we make these movable?
  using receiver_list =
    std::multimap<std::string, pqxx::notification_receiver *>;
  receiver_list m_receivers;
 
 
  std::map<std::string, notification_handler> m_notification_handlers;
 
  sl m_created_loc;
 
  int m_unique_id = 0;
};
 
 
 
class PQXX_LIBEXPORT connecting final
{
public:
  explicit connecting(zview connection_string = ""_zv, sl = sl::current());
 
  connecting(connecting const &) = delete;
  connecting(connecting &&) = default;
  ~connecting() = default;
  connecting &operator=(connecting const &) = delete;
  connecting &operator=(connecting &&) = default;
 
  [[nodiscard]] int sock() const & noexcept { return m_conn.sock(); }
 
  [[nodiscard]] constexpr bool wait_to_read() const & noexcept
  {
    return m_reading;
  }
 
  [[nodiscard]] constexpr bool wait_to_write() const & noexcept
  {
    return m_writing;
  }
 
  void process(sl loc = sl::current()) &;
 
  [[nodiscard]] constexpr bool done() const & noexcept
  {
    return not m_reading and not m_writing;
  }
 
 
  [[nodiscard]] connection produce(sl = sl::current()) &&;
 
private:
  connection m_conn;
  bool m_reading{false};
  bool m_writing{true};
};
 
 
template<typename T>
inline std::string connection::quote(T const &t, sl loc) const
{
  if (is_null(t))
  {
    // It's easy to forget, but we can't support nulls in string conversion
    // itself, because the "NULL" may end up inside quotes or something.
    // We can only handle nulls at this slightly higher level in the call tree,
    // where there is awareness of the quoting.
    return "NULL";
  }
  else if constexpr (binary<T>)
  {
    return quote_raw(t);
  }
  else
  {
    // TODO: Can we leave the quotes out if unquoted_safe?
    auto const text{to_string(t)};
 
    // Okay, there's an easy way to do this and there's a hard way.  The easy
    // way was "quote, esc(to_string(t)), quote".  I'm going with the hard way
    // because it's going to save some string manipulation that will probably
    // incur some unnecessary memory allocations and deallocations.
    std::string buf{'\''};
    buf.resize(2 + 2 * std::size(text) + 1);
    auto const content_bytes{
      esc_to_buf(text, {std::begin(buf) + 1, std::end(buf)}, loc)};
    auto const closing_quote{1 + content_bytes};
    buf[closing_quote] = '\'';
    auto const end{closing_quote + 1};
    buf.resize(end);
    return buf;
  }
}
 
 
template<pqxx::char_strings STRINGS>
inline std::string
connection::quote_columns(STRINGS const &columns, sl loc) const
{
  conversion_context const c{get_encoding_group(), loc};
  return separated_list(
    ","sv, std::cbegin(columns), std::cend(columns),
    [this](auto col) { return this->quote_name(*col); }, c);
}
 
 
template<pqxx::ZString STRING, ZKey_ZValues MAPPING>
inline connection::connection(
  STRING const &connection_string, MAPPING &&params, sl loc) :
        m_created_loc{loc}
{
  // Check that the libpqxx binary library version is compatible with the
  // version against which the application was compiled.  We're in an inline
  // function, so this _call_ ends up in the application binary.  On the other
  // hand, `check_libpqxx_version()` is compiled into the libpqx binary.
  // That's how the function is in a position to compare the two versions.
  //
  // There is no particular reason to do this here in @ref connection, except
  // to ensure that every meaningful libpqxx client will execute it, while
  // minimising overhead.  The ideal would be to pay a small price exactly once
  // per application run.
  //
  // A local static variable is initialised only on the definition's first
  // execution.  Compilers will be well optimised for this, so there's a
  // minimal one-time cost.
  [[maybe_unused]] static auto const version_check{
    pqxx::internal::check_libpqxx_version(
      version_major, version_minor, version_patch, version)};
 
  // clang-tidy rule bug:
  // NOLINTBEGIN(
  //    cppcoreguidelines-pro-bounds-array-to-pointer-decay,
  //    hicpp-no-array-decay
  // )
  pqxx::internal::connection_string_parser const parsed_string{
    pqxx::internal::as_c_string(connection_string), loc};
  // NOLINTEND(
  //    cppcoreguidelines-pro-bounds-array-to-pointer-decay,
  //    hicpp-no-array-decay
  // )
  auto [keys, values]{parsed_string.parse()};
 
  // Merge key/value pairs into the pairs we got from the connection string.
  for (auto const &[org_key, org_value] : params)
  {
    auto const key{pqxx::internal::as_c_string(org_key)},
      value{pqxx::internal::as_c_string(org_value)};
 
    // Did we have a value for key already?  This is a horrible O(n^2) search,
    // in principle, but there's only so many possible options.  Trying to
    // optimise this might make it worse in common practical cases.
    //
    // (Landau's "large O" notation really only applies to inputs growing
    // towards infinity.  If there's a known constant bound b such that n < b,
    // then O(n^2) is at worst O(b^2).  Since b is a constant, O(b^2) boils
    // down to O(1).)
    auto const it{std::ranges::find_if(keys, [key](char const *existing) {
      return std::strcmp(existing, key) == 0;
    })};
 
    if (it == keys.end())
    {
      // New key.  Append.
      keys.push_back(key);
      values.push_back(value);
    }
    else
    {
      // A key we've already seen.  Override.
      auto const idx{
        static_cast<std::size_t>(std::distance(keys.begin(), it))};
      values[idx] = value;
    }
  }
 
  // Null-terminate both arrays.
  keys.push_back(nullptr);
  values.push_back(nullptr);
 
  init(keys, values, loc);
}
} // namespace pqxx
#endif