except.hxx

Go to the documentation of this file.

/* Definition of libpqxx exception classes.
 *
 * pqxx::sql_error, pqxx::broken_connection, pqxx::in_doubt_error, ...
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/except 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_EXCEPT_HXX
#define PQXX_EXCEPT_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <memory>
#include <stdexcept>
#include <string>
 
#include "pqxx/types.hxx"
 
 
namespace pqxx
{
struct PQXX_LIBEXPORT failure : std::exception
{
  failure(failure const &) = default;
  failure(failure &&) = default;
  explicit failure(sl loc = sl::current(), st tr = st::current()) :
          m_block{std::make_shared<block>(loc, std::move(tr))}
  {}
  explicit failure(
    std::string whatarg, sl loc = sl::current(), st tr = st::current()) :
          m_block{
            std::make_shared<block>(std::move(whatarg), loc, std::move(tr))}
  {}
 
  ~failure() noexcept override;
 
  failure &operator=(failure const &) = default;
  failure &operator=(failure &&) = default;
 
  [[nodiscard]] PQXX_PURE char const *what() const noexcept override
  {
    return m_block->message.c_str();
  }
 
 
  [[nodiscard]] PQXX_PURE sl const &location() const noexcept
  {
    return m_block->location;
  }
 
 
  [[nodiscard]] PQXX_PURE std::shared_ptr<st const> trace() const noexcept
  {
    return m_block->trace;
  }
 
 
  [[nodiscard]] PQXX_PURE std::string_view sqlstate() const noexcept
  {
    return m_block->sqlstate;
  }
 
 
  [[nodiscard]] PQXX_PURE std::string_view query() const noexcept
  {
    return m_block->statement;
  }
 
 
  [[nodiscard]] virtual bool poisons_connection() const noexcept
  {
    return false;
  }
 
 
  [[nodiscard]] virtual bool poisons_transaction() const noexcept
  {
    return false;
  }
 
  // C++26: Implement using reflection.
 
  [[nodiscard]] virtual std::string_view name() const noexcept;
 
protected:
  failure(
    std::string whatarg, std::string stat, std::string sqls,
    sl loc = sl::current(), st tr = st::current()) :
          m_block{std::make_shared<block>(
            std::move(whatarg), std::move(stat), std::move(sqls), loc,
            std::move(tr))}
  {}
 
private:
  struct block final
  {
    // NOLINTBEGIN(misc-non-private-member-variables-in-classes)
 
    std::string message;
    std::string statement;
    std::string sqlstate;
    sl location;
    std::shared_ptr<st const> trace;
 
    // NOLINTEND(misc-non-private-member-variables-in-classes)
 
    block(sl loc, st &&tr) :
            location{loc}, trace{make_trace_ptr(std::move(tr))}
    {}
 
    block(std::string &&msg, sl loc, st &&tr) :
            message{std::move(msg)},
            location{loc},
            trace{make_trace_ptr(std::move(tr))}
    {}
 
    block(
      std::string &&msg, std::string &&stat, std::string &&sqls, sl loc,
      st &&tr) :
            message{std::move(msg)},
            statement{std::move(stat)},
            sqlstate{std::move(sqls)},
            location{loc},
            trace{make_trace_ptr(std::move(tr))}
    {}
 
 
    [[nodiscard]] static std::shared_ptr<st const>
    make_trace_ptr([[maybe_unused]] st &&tr)
    {
#if defined(PQXX_HAVE_STACKTRACE)
      // We have std::stacktrace support.  Move tr from the stack to the heap.
      return std::make_shared<st const>(std::move(tr));
#else
      // We don't have std::stacktrace.  Keep the pointer empty.
      return {};
#endif
    }
  };
 
 
  std::shared_ptr<block const> m_block;
};
 
 
 
struct PQXX_LIBEXPORT broken_connection : failure
{
  explicit broken_connection(sl loc = sl::current(), st &&tr = st::current()) :
          failure{"Connection to database failed.", loc, std::move(tr)}
  {}
 
  explicit broken_connection(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
};
 
 
struct PQXX_LIBEXPORT version_mismatch : broken_connection
{
  explicit version_mismatch(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          broken_connection{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT variable_set_to_null : failure
{
  explicit variable_set_to_null(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
 
struct PQXX_LIBEXPORT sql_error : public failure
{
  PQXX_ZARGS explicit sql_error(
    std::string const &whatarg = {}, std::string const &stmt = {},
    std::string const &sqls = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, stmt, sqls, loc, std::move(tr)}
  {}
  sql_error(sql_error const &other) = default;
  sql_error(sql_error &&other) = default;
  ~sql_error() override = default;
 
  sql_error &operator=(sql_error const &other) = default;
  sql_error &operator=(sql_error &&other) = default;
 
  [[nodiscard]] std::string_view name() const noexcept override;
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
};
 
 
 
struct PQXX_LIBEXPORT protocol_violation : sql_error
{
  explicit protocol_violation(
    std::string const &whatarg, std::string const &stmt = {},
    std::string const &sqls = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{whatarg, stmt, sqls, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
 
struct PQXX_LIBEXPORT in_doubt_error : failure
{
  explicit in_doubt_error(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT transaction_rollback : sql_error
{
  PQXX_ZARGS explicit transaction_rollback(
    std::string const &whatarg, std::string const &q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{whatarg, q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
 
struct PQXX_LIBEXPORT serialization_failure : transaction_rollback
{
  PQXX_ZARGS explicit serialization_failure(
    std::string const &whatarg, std::string const &q,
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          transaction_rollback{whatarg, q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT statement_completion_unknown : transaction_rollback
{
  PQXX_ZARGS explicit statement_completion_unknown(
    std::string const &whatarg, std::string const &q,
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          transaction_rollback{whatarg, q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT deadlock_detected : transaction_rollback
{
  PQXX_ZARGS explicit deadlock_detected(
    std::string const &whatarg, std::string const &q,
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          transaction_rollback{whatarg, q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT internal_error : failure
{
  explicit internal_error(
    std::string const &, sl = sl::current(), st &&tr = st::current());
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT usage_error : failure
{
  explicit usage_error(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT argument_error : failure
{
  explicit argument_error(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT conversion_error : failure
{
  explicit conversion_error(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT unexpected_null : conversion_error
{
  explicit unexpected_null(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          conversion_error{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT conversion_overrun : conversion_error
{
  explicit conversion_overrun(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          conversion_error{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT range_error : failure
{
  explicit range_error(
    std::string const &whatarg, sl loc = sl::current(),
    st &&tr = st::current()) :
          failure{whatarg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT unexpected_rows : range_error
{
  explicit unexpected_rows(
    std::string const &msg, sl loc = sl::current(), st &&tr = st::current()) :
          range_error{msg, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT feature_not_supported : sql_error
{
  PQXX_ZARGS explicit feature_not_supported(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
 
  [[nodiscard]] bool poisons_connection() const noexcept override
  {
    return true;
  }
 
  [[nodiscard]] bool poisons_transaction() const noexcept override
  {
    return true;
  }
};
 
 
struct PQXX_LIBEXPORT data_exception : sql_error
{
  PQXX_ZARGS explicit data_exception(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT integrity_constraint_violation : sql_error
{
  PQXX_ZARGS explicit integrity_constraint_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT restrict_violation : integrity_constraint_violation
{
  PQXX_ZARGS explicit restrict_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          integrity_constraint_violation{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT not_null_violation : integrity_constraint_violation
{
  PQXX_ZARGS explicit not_null_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          integrity_constraint_violation{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT foreign_key_violation : integrity_constraint_violation
{
  PQXX_ZARGS explicit foreign_key_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          integrity_constraint_violation{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT unique_violation : integrity_constraint_violation
{
  PQXX_ZARGS explicit unique_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          integrity_constraint_violation{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT check_violation : integrity_constraint_violation
{
  PQXX_ZARGS explicit check_violation(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          integrity_constraint_violation{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT invalid_cursor_state : sql_error
{
  PQXX_ZARGS explicit invalid_cursor_state(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT invalid_sql_statement_name : sql_error
{
  PQXX_ZARGS explicit invalid_sql_statement_name(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT invalid_cursor_name : sql_error
{
  PQXX_ZARGS explicit invalid_cursor_name(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT syntax_error : sql_error
{
  // NOLINTNEXTLINE(misc-non-private-member-variables-in-classes)
  [[deprecated("Call error_pos() instead.")]] int error_position;
 
#include "pqxx/internal/ignore-deprecated-pre.hxx"
 
  PQXX_ZARGS explicit syntax_error(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, int pos = -1, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}, error_position{pos}
  {}
 
#include "pqxx/internal/ignore-deprecated-post.hxx"
 
  [[nodiscard]] std::string_view name() const noexcept override;
 
 
  [[nodiscard]] constexpr int error_pos() const noexcept
  {
#include "pqxx/internal/ignore-deprecated-pre.hxx"
    return error_position;
#include "pqxx/internal/ignore-deprecated-post.hxx"
  }
};
 
 
struct PQXX_LIBEXPORT undefined_column : syntax_error
{
  PQXX_ZARGS explicit undefined_column(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          // TODO: Can we get the column?
          syntax_error{err, Q, sqlstate, -1, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT undefined_function : syntax_error
{
  PQXX_ZARGS explicit undefined_function(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          // TODO: Can we get the column?
          syntax_error{err, Q, sqlstate, -1, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT undefined_table : syntax_error
{
  PQXX_ZARGS explicit undefined_table(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          // TODO: Can we get the column?
          syntax_error{err, Q, sqlstate, -1, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT insufficient_privilege : sql_error
{
  PQXX_ZARGS explicit insufficient_privilege(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT insufficient_resources : sql_error
{
  PQXX_ZARGS explicit insufficient_resources(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT disk_full : insufficient_resources
{
  PQXX_ZARGS explicit disk_full(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          insufficient_resources{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT server_out_of_memory : insufficient_resources
{
  PQXX_ZARGS explicit server_out_of_memory(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          insufficient_resources{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT too_many_connections : broken_connection
{
  explicit too_many_connections(
    std::string const &err, sl loc = sl::current(), st &&tr = st::current()) :
          broken_connection{err, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
 
struct PQXX_LIBEXPORT plpgsql_error : sql_error
{
  PQXX_ZARGS explicit plpgsql_error(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          sql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT plpgsql_raise : plpgsql_error
{
  PQXX_ZARGS explicit plpgsql_raise(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          plpgsql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT plpgsql_no_data_found : plpgsql_error
{
  PQXX_ZARGS explicit plpgsql_no_data_found(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          plpgsql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
 
struct PQXX_LIBEXPORT plpgsql_too_many_rows : plpgsql_error
{
  PQXX_ZARGS explicit plpgsql_too_many_rows(
    std::string const &err, std::string const &Q = {},
    std::string const &sqlstate = {}, sl loc = sl::current(),
    st &&tr = st::current()) :
          plpgsql_error{err, Q, sqlstate, loc, std::move(tr)}
  {}
 
  [[nodiscard]] std::string_view name() const noexcept override;
};
 
} // namespace pqxx
#endif