transaction.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/storages/mysql/transaction.hpp
 
#include <userver/tracing/span.hpp>
#include <userver/utils/fast_pimpl.hpp>
#include <userver/utils/trx_tracker.hpp>
 
#include <userver/storages/mysql/cluster_host_type.hpp>
#include <userver/storages/mysql/command_result_set.hpp>
#include <userver/storages/mysql/cursor_result_set.hpp>
#include <userver/storages/mysql/impl/bind_helper.hpp>
#include <userver/storages/mysql/options.hpp>
#include <userver/storages/mysql/query.hpp>
#include <userver/storages/mysql/statement_result_set.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace storages::mysql {
 
namespace infra {
class ConnectionPtr;
}
 
/// @brief RAII transaction wrapper, auto-<b>ROLLBACK</b>s on destruction if no
/// prior `Commit`/`Rollback` call was made.
///
/// This type can't be constructed in user code and is always retrieved from
/// storages::mysql::Cluster
class Transaction final {
public:
    explicit Transaction(infra::ConnectionPtr&& connection, engine::Deadline deadline);
    ~Transaction();
    Transaction(const Transaction& other) = delete;
    Transaction(Transaction&& other) noexcept;
 
    /// @brief Executes a statement with default deadline.
    /// Fills placeholders of the statement with args..., `Args` are expected to
    /// be of supported types.
    /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of `Args`
    /// requirements.
    ///
    /// UINVARIANTs on params count mismatch doesn't validate types.
    template <typename... Args>
    StatementResultSet Execute(const Query& query, const Args&... args) const;
 
    /// @brief Executes a statement with default deadline.
    ///
    /// Basically an alias for Execute(host_type, query, AsArgs<T>(row)),
    /// where AsArgs is an imaginary function which passes fields of T as
    /// variadic params. Handy for one-liner inserts.
    /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of `T` requirements.
    ///
    /// UINVARIANTs on params count mismatch, doesn't validate types.
    template <typename T>
    StatementResultSet ExecuteDecompose(const Query& query, const T& row) const;
 
    /// @brief Executes a statement with default deadline.
    /// Fills placeholders of the statements with Container::value_type in a
    /// bulk-manner.
    /// Container is expected to be a std::Container, Container::value_type is
    /// expected to be an aggregate of supported types.
    /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of
    /// `Container::value_type` requirements.
    ///
    /// @note Requires MariaDB 10.2.6+ as a server
    ///
    /// UINVARIANTs on params count mismatch, doesn't validate types.
    /// UINVARIANTs on empty params container.
    template <typename Container>
    StatementResultSet ExecuteBulk(const Query& query, const Container& params) const;
 
    // TODO : don't require Container to be const, so Convert can move
    // clang-format off
  /// @brief Executes a statement with default deadline,
  /// on the flight remapping from `Container::value_type` to `MapTo`.
  /// `Container` is expected to be a std::Container of whatever type pleases
  /// you, `MapTo` is expected to be an aggregate of supported types.
  /// See @ref scripts/docs/en/userver/mysql/supported_types.md for better understanding of `MapTo` requirements.
  /// You are expected to provide a converter function
  /// `MapTo Convert(const Container::value_type&, storages::mysql::convert::To<MapTo>)`
  /// in namespace of `MapTo` or storages::mysql::convert.
  ///
  /// @note Requires MariaDB 10.2.6+ as a server
  ///
  /// UINVARIANTs on params count mismatch, doesn't validate types.
  /// UINVARIANTs on empty params container.
  template <typename MapTo, typename Container>
  StatementResultSet ExecuteBulkMapped(const Query& query,
                                       const Container& params) const;
    // clang-format on
 
    /// @brief Commit the transaction
    void Commit();
 
    /// @brief Rollback the transaction
    void Rollback();
 
private:
    StatementResultSet DoExecute(const Query& query, impl::io::ParamsBinderBase& params) const;
 
    void AssertValid() const;
 
    utils::FastPimpl<infra::ConnectionPtr, 24, 8> connection_;
    engine::Deadline deadline_;
    tracing::Span span_;
    utils::trx_tracker::TransactionLock trx_lock_;
};
 
template <typename... Args>
StatementResultSet Transaction::Execute(const Query& query, const Args&... args) const {
    auto params_binder = impl::BindHelper::BindParams(args...);
 
    return DoExecute(query, params_binder);
}
 
template <typename T>
StatementResultSet Transaction::ExecuteDecompose(const Query& query, const T& row) const {
    auto params_binder = impl::BindHelper::BindRowAsParams(row);
 
    return DoExecute(query, params_binder);
}
 
template <typename Container>
StatementResultSet Transaction::ExecuteBulk(const Query& query, const Container& params) const {
    UINVARIANT(!params.empty(), "Empty params in bulk execution");
 
    auto params_binder = impl::BindHelper::BindContainerAsParams(params);
 
    return DoExecute(query, params_binder);
}
 
template <typename MapTo, typename Container>
StatementResultSet Transaction::ExecuteBulkMapped(const Query& query, const Container& params) const {
    UINVARIANT(!params.empty(), "Empty params in bulk execution");
 
    auto params_binder = impl::BindHelper::BindContainerAsParamsMapped<MapTo>(params);
 
    return DoExecute(query, params_binder);
}
 
}  // namespace storages::mysql
 
USERVER_NAMESPACE_END