statement_result_set.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/storages/mysql/statement_result_set.hpp
 
#include <optional>
#include <vector>
 
#include <fmt/format.h>
 
#include <userver/engine/deadline.hpp>
#include <userver/tracing/scope_time.hpp>
#include <userver/utils/fast_pimpl.hpp>
 
#include <userver/storages/mysql/execution_result.hpp>
#include <userver/storages/mysql/impl/io/extractor.hpp>
#include <userver/storages/mysql/impl/tracing_tags.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace storages::mysql {
 
namespace impl {
class StatementFetcher;
}
 
namespace infra {
class ConnectionPtr;
}
 
template <typename DbType>
class MappedStatementResultSet;
 
/// @brief A wrapper for statement execution result.
///
/// This type can't be constructed in user code and is always retrieved from
/// storages::mysql::Cluster or storages::mysql::Transaction methods.
class StatementResultSet final {
 public:
  explicit StatementResultSet(impl::StatementFetcher&& fetcher,
                              tracing::Span&& span);
  StatementResultSet(infra::ConnectionPtr&& connection,
                     impl::StatementFetcher&& fetcher, tracing::Span&& span);
  ~StatementResultSet();
 
  StatementResultSet(const StatementResultSet& other) = delete;
  StatementResultSet(StatementResultSet&& other) noexcept;
 
  // clang-format off
  /// @brief Parse statement result set as std::vector<T>.
  /// `T` is expected to be an aggregate of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
  /// `T` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsVector
  // clang-format on
  template <typename T>
  std::vector<T> AsVector() &&;
 
  // clang-format off
  /// @brief Parse statement result set as std::vector<T>.
  /// Result set is expected to have a single column, `T` is expected to be one
  /// of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported typed.
  ///
  /// UINVARIANTs on columns count not being equal to 1 or type mismatch.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsVectorFieldTag
  // clang-format on
  template <typename T>
  std::vector<T> AsVector(FieldTag) &&;
 
  // clang-format off
  /// @brief Parse statement result set as Container<T>.
  /// `T` is expected to be an aggregate of supported types, `Container` is
  /// expected to meet std::Container requirements.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
  /// `Container::value_type` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsContainer
  // clang-format on
  template <typename Container>
  Container AsContainer() &&;
 
  // clang-format off
  /// @brief Parse statement result as Container<T>.
  /// Result set is expected to have a single column, `T` is expected to be one
  /// of supported types,
  /// `Container` is expected to meed std::Container requirements.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported types.
  ///
  /// UINVARIANTs on columns count not being equal to 1 or type mismatch.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsContainerFieldTag
  // clang-format on
  template <typename Container>
  Container AsContainer(FieldTag) &&;
 
  // clang-format off
  /// @brief Parse statement result as T.
  /// Result set is expected to have a single row, `T` is expected to be an
  /// aggregate of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
  /// `T` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch.
  /// throws if result set is empty or contains more than one row.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsSingleRow
  // clang-format on
  template <typename T>
  T AsSingleRow() &&;
 
  // clang-format off
  /// @brief Parse statement result as T.
  /// Result set is expected to have a single row and a single column,
  /// `T` is expected to be one of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported types.
  ///
  /// UINVARIANTs on columns count not being equal to 1 or type mismatch.
  /// throws if result set is empty of contains more than one row.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsSingleField
  // clang-format on
  template <typename T>
  T AsSingleField() &&;
 
  // clang-format off
  /// @brief Parse statement result as std::optional<T>.
  /// Result set is expected to have not more than one row,
  /// `T` is expected to be an aggregate of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
  /// `T` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch.
  /// throws if result set contains more than one row.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsOptionalSingleRow
  // clang-format on
  template <typename T>
  std::optional<T> AsOptionalSingleRow() &&;
 
  // clang-format off
  /// @brief Parse statement result as T.
  /// Result set is expected to have not more than one row,
  /// `T` is expected to be one of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported types.
  ///
  /// UINVARIANTs on columns count not being equal to 1 or type mismatch.
  /// throws if result set contains more than one row.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet AsOptionalSingleField
  // clang-format on
  template <typename T>
  std::optional<T> AsOptionalSingleField() &&;
 
  // clang-format off
  /// @brief Converts to an interface for on-the-flight mapping
  /// statement result set from `DbType`.
  /// `DbType` is expected to be an aggregate of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
  /// `DbType` requirements.
  ///
  /// @snippet storages/tests/unittests/statement_result_set_mysqltest.cpp uMySQL usage sample - StatementResultSet MapFrom
  // clang-format on
  template <typename DbType>
  MappedStatementResultSet<DbType> MapFrom() &&;
 
  /// @brief Get statement execution metadata.
  ExecutionResult AsExecutionResult() &&;
 
 private:
  template <typename T>
  friend class CursorResultSet;
 
  template <typename DbType>
  friend class MappedStatementResultSet;
 
  template <typename Container, typename MapFrom, typename ExtractionTag>
  Container DoAsContainerMapped() &&;
 
  template <typename T, typename ExtractionTag>
  std::optional<T> DoAsOptionalSingleRow() &&;
 
  bool FetchResult(impl::io::ExtractorBase& extractor);
 
  struct Impl;
  utils::FastPimpl<Impl, 72, 8> impl_;
};
 
/// @brief An interface for on-the-flight mapping statement result set from
/// DbType into whatever type you provide without additional allocations.
///
/// `DbType` is expected to be either an aggregate of supported types or a
/// supported type itself for methods taking `FieldTag`; DbType is expected
/// to match DB representation - same amount of columns (1 for `FieldTag`
/// overload) and matching types.
///
/// You are expected to provide a converter function
/// `T Convert(DbType&&, storages::mysql::convert:To<T>)` in either
/// T's namespace or `storages::mysql::convert` namespace
template <typename DbType>
class MappedStatementResultSet final {
 public:
  explicit MappedStatementResultSet(StatementResultSet&& result_set);
  ~MappedStatementResultSet();
 
  /// @brief Parse statement result set as std::vector<T> using provided
  /// converter function.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better
  /// understanding of `T` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch for `DbType`.
  template <typename T>
  std::vector<T> AsVector() &&;
 
  /// @brief Parse statement result set as std::vector<T> using provided
  /// converter function.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported
  /// types.
  ///
  /// UINVARIANTs on columns count not being 1 or types mismatch for DbType.
  template <typename T>
  std::vector<T> AsVector(FieldTag) &&;
 
  /// @brief Parse statement result set as Container<T> using provided
  /// converter function.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better
  /// understanding of `Container::value_type` requirements.
  ///
  /// UINVARIANTs on columns count mismatch or types mismatch for `DbType`.
  template <typename Container>
  Container AsContainer() &&;
 
  /// @brief Parse statement result set as Container<T> using provided
  /// converter function.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for supported
  /// types.
  ///
  /// UINVARIANTs on columns count not being 1 or types mismatch for DbType.
  template <typename Container>
  Container AsContainer(FieldTag) &&;
 
  template <typename T>
  T AsSingleRow() && {
    static_assert(!sizeof(T),
                  "Not implemented, just use StatementResultSet version and "
                  "convert yourself.");
  }
 
  template <typename T>
  std::optional<T> AsOptionalSingleRow() && {
    static_assert(!sizeof(T),
                  "Not implemented, just use StatementResultSet version and "
                  "convert yourself.");
  }
 
 private:
  StatementResultSet result_set_;
};
 
template <typename T>
std::vector<T> StatementResultSet::AsVector() && {
  return std::move(*this).AsContainer<std::vector<T>>();
}
 
template <typename T>
std::vector<T> StatementResultSet::AsVector(FieldTag) && {
  return std::move(*this).AsContainer<std::vector<T>>(kFieldTag);
}
 
template <typename Container>
Container StatementResultSet::AsContainer() && {
  static_assert(meta::kIsRange<Container>,
                "The type isn't actually a container");
  using Row = typename Container::value_type;
 
  return std::move(*this).DoAsContainerMapped<Container, Row, RowTag>();
}
 
template <typename Container>
Container StatementResultSet::AsContainer(FieldTag) && {
  static_assert(meta::kIsRange<Container>,
                "The type isn't actually a container");
  using Row = typename Container::value_type;
 
  return std::move(*this).DoAsContainerMapped<Container, Row, FieldTag>();
}
 
template <typename T>
T StatementResultSet::AsSingleRow() && {
  auto optional_data = std::move(*this).AsOptionalSingleRow<T>();
 
  if (!optional_data.has_value()) {
    throw std::runtime_error{"Result set is empty"};
  }
 
  return std::move(*optional_data);
}
 
template <typename T>
T StatementResultSet::AsSingleField() && {
  auto optional_data = std::move(*this).AsOptionalSingleField<T>();
 
  if (!optional_data.has_value()) {
    throw std::runtime_error{"Result set is empty"};
  }
 
  return std::move(*optional_data);
}
 
template <typename T>
std::optional<T> StatementResultSet::AsOptionalSingleRow() && {
  return std::move(*this).DoAsOptionalSingleRow<T, RowTag>();
}
 
template <typename T>
std::optional<T> StatementResultSet::AsOptionalSingleField() && {
  return std::move(*this).DoAsOptionalSingleRow<T, FieldTag>();
}
 
template <typename Container, typename MapFrom, typename ExtractionTag>
Container StatementResultSet::DoAsContainerMapped() && {
  static_assert(meta::kIsRange<Container>,
                "The type isn't actually a container");
  using Extractor = impl::io::TypedExtractor<Container, MapFrom, ExtractionTag>;
 
  Extractor extractor{};
 
  tracing::ScopeTime fetch{impl::tracing::kFetchScope};
  std::move(*this).FetchResult(extractor);
  fetch.Reset();
 
  return Container{extractor.ExtractData()};
}
 
template <typename T, typename ExtractionTag>
std::optional<T> StatementResultSet::DoAsOptionalSingleRow() && {
  auto rows = [this] {
    if constexpr (std::is_same_v<RowTag, ExtractionTag>) {
      return std::move(*this).AsVector<T>();
    } else {
      return std::move(*this).AsVector<T>(kFieldTag);
    }
  }();
 
  if (rows.empty()) {
    return std::nullopt;
  }
 
  if (rows.size() > 1) {
    throw std::runtime_error{fmt::format(
        "There is more than one row in result set ({} rows)", rows.size())};
  }
 
  return {std::move(rows.front())};
}
 
template <typename DbType>
MappedStatementResultSet<DbType>::MappedStatementResultSet(
    StatementResultSet&& result_set)
    : result_set_{std::move(result_set)} {}
 
template <typename DbType>
MappedStatementResultSet<DbType>::~MappedStatementResultSet() = default;
 
template <typename DbType>
template <typename T>
std::vector<T> MappedStatementResultSet<DbType>::AsVector() && {
  return std::move(*this).template AsContainer<std::vector<T>>();
}
 
template <typename DbType>
template <typename T>
std::vector<T> MappedStatementResultSet<DbType>::AsVector(FieldTag) && {
  return std::move(*this).template AsContainer<std::vector<T>>(kFieldTag);
}
 
template <typename DbType>
template <typename Container>
Container MappedStatementResultSet<DbType>::AsContainer() && {
  return std::move(result_set_)
      .DoAsContainerMapped<Container, DbType, RowTag>();
}
 
template <typename DbType>
template <typename Container>
Container MappedStatementResultSet<DbType>::AsContainer(FieldTag) && {
  return std::move(result_set_)
      .DoAsContainerMapped<Container, DbType, FieldTag>();
}
 
template <typename DbType>
MappedStatementResultSet<DbType> StatementResultSet::MapFrom() && {
  return MappedStatementResultSet<DbType>{std::move(*this)};
}
 
}  // namespace storages::mysql
 
USERVER_NAMESPACE_END