storages::mysql::Cluster Class Reference

Table of Contents

• Public Member Functions
• Detailed Description
• Member Function Documentation
• Begin() [1/2]
• Begin() [2/2]
• Execute() [1/2]
• Execute() [2/2]
• ExecuteBulk() [1/2]
• ExecuteBulk() [2/2]
• ExecuteBulkMapped() [1/2]
• ExecuteBulkMapped() [2/2]
• ExecuteCommand() [1/2]
• ExecuteCommand() [2/2]
• ExecuteDecompose() [1/2]
• ExecuteDecompose() [2/2]
• GetCursor() [1/2]
• GetCursor() [2/2]

Client interface for a cluster of MySQL servers. Usually retrieved from components::MySQL. More...

#include </data/code/service_template/third_party/userver/mysql/include/userver/storages/mysql/cluster.hpp>

Public Member Functions
	Cluster (clients::dns::Resolver &resolver, const settings::MysqlSettings &settings, const components::ComponentConfig &config)
	Cluster constructor.
	~Cluster ()
	Cluster destructor.
template<typename... Args>
StatementResultSet	Execute (ClusterHostType host_type, const Query &query, const Args &... args) const
	Executes a statement on a host of host_type with default deadline. Fills placeholders of the statement with args..., Args are expected to be of supported types. See MySQL supported types for better understanding of Args requirements.
template<typename... Args>
StatementResultSet	Execute (OptionalCommandControl command_control, ClusterHostType host_type, const Query &query, const Args &... args) const
	Executes a statement on a host of host_type with provided CommandControl. Fills placeholders of the statement with args..., Args are expected to be of supported types. See MySQL supported types for better understanding of Args requirements.
template<typename T >
StatementResultSet	ExecuteDecompose (ClusterHostType host_type, const Query &query, const T &row) const
	Executes a statement on a host of host_type with default deadline.
template<typename T >
StatementResultSet	ExecuteDecompose (OptionalCommandControl command_control, ClusterHostType host_type, const Query &query, const T &row) const
	Executes a statement on a host of host_type with provided CommandControl.
template<typename Container >
StatementResultSet	ExecuteBulk (ClusterHostType host_type, const Query &query, const Container &params) const
	Executes a statement on a host of host_type 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 MySQL supported types for better understanding of Container::value_type requirements.
template<typename Container >
StatementResultSet	ExecuteBulk (OptionalCommandControl command_control, ClusterHostType host_type, const Query &query, const Container &params) const
	Executes a statement on a host of host_type with provided CommandControl. 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 MySQL supported types for better understanding of Container::value_type requirements.
template<typename MapTo , typename Container >
StatementResultSet	ExecuteBulkMapped (ClusterHostType host_type, const Query &query, const Container &params) const
	Executes a statement on a host of host_type 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 MySQL supported types 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.
template<typename MapTo , typename Container >
StatementResultSet	ExecuteBulkMapped (OptionalCommandControl command_control, ClusterHostType host_type, const Query &query, const Container &params) const
	Executes a statement on a host of host_type with provided CommandControl, 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 MySQL supported types 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.
Transaction	Begin (ClusterHostType host_type) const
	Begin a transaction with default deadline.
Transaction	Begin (OptionalCommandControl command_control, ClusterHostType host_type) const
	Being a transaction with specified CommandControl.
CommandResultSet	ExecuteCommand (ClusterHostType host_type, const Query &command) const
	Executes a command on host of type host_type over plan-text protocol, with default deadline.
CommandResultSet	ExecuteCommand (OptionalCommandControl command_control, ClusterHostType host_type, const Query &command) const
	Executes a command on host of type host_type over plan-text protocol, with provided CommandControl.
template<typename T , typename... Args>
CursorResultSet< T >	GetCursor (ClusterHostType host_type, std::size_t batch_size, const Query &query, const Args &... args) const
	Executes a statement with default deadline on a host of host_type, filling statements placeholders with args..., and returns a read-only cursor which fetches batch_count rows in each next fetch request. See MySQL supported types for better understanding of Args requirements.
template<typename T , typename... Args>
CursorResultSet< T >	GetCursor (OptionalCommandControl command_control, ClusterHostType host_type, std::size_t batch_size, const Query &query, const Args &... args) const
	Executes a statement with provided CommandControl on a host of host_type, filling statements placeholders with args..., and returns a read-only cursor which fetches batch_count rows in each next fetch request. See MySQL supported types for better understanding of Args requirements.
void	WriteStatistics (utils::statistics::Writer &writer) const
	Write cluster statistics.

Detailed Description

Client interface for a cluster of MySQL servers. Usually retrieved from components::MySQL.

Definition at line 40 of file cluster.hpp.

Member Function Documentation

Begin() [1/2]

Transaction storages::mysql::Cluster::Begin

(

ClusterHostType

host_type

)

const

Begin a transaction with default deadline.

Note

The deadline is transaction-wide, not just for Begin query itself.

Parameters

host_type

Host type on which to execute transaction.

Begin() [2/2]

Transaction storages::mysql::Cluster::Begin	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type
	)		const

Being a transaction with specified CommandControl.

Note

The deadline is transaction-wide, not just for Begin query itself.

Parameters

host_type

Host type on which to execute transaction.

Execute() [1/2]

template<typename... Args>

StatementResultSet storages::mysql::Cluster::Execute	(	ClusterHostType	host_type,
		const Query &	query,
		const Args &...	args
	)		const

Executes a statement on a host of host_type with default deadline. Fills placeholders of the statement with args..., Args are expected to be of supported types. See MySQL supported types for better understanding of Args requirements.

UINVARIANTs on params count mismatch doesn't validate types.

Definition at line 278 of file cluster.hpp.

Execute() [2/2]

template<typename... Args>

StatementResultSet storages::mysql::Cluster::Execute	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		const Query &	query,
		const Args &...	args
	)		const

Executes a statement on a host of host_type with provided CommandControl. Fills placeholders of the statement with args..., Args are expected to be of supported types. See MySQL supported types for better understanding of Args requirements.

UINVARIANTs on params count mismatch doesn't validate types.

void PerformExecute(const Cluster& cluster, std::chrono::milliseconds timeout,
                    const std::string& title, int amount) {
  const auto insertion_result =
      cluster
          .Execute(CommandControl{timeout}, ClusterHostType::kPrimary,
                   "INSERT INTO SampleTable(title, amount, created) "
                   "VALUES(?, ?, ?)",
                   title, amount, std::chrono::system_clock::now())
          .AsExecutionResult();
 
  EXPECT_EQ(insertion_result.rows_affected, 1);
  EXPECT_EQ(insertion_result.last_insert_id, 1);
}

Definition at line 285 of file cluster.hpp.

ExecuteBulk() [1/2]

template<typename Container >

StatementResultSet storages::mysql::Cluster::ExecuteBulk	(	ClusterHostType	host_type,
		const Query &	query,
		const Container &	params
	)		const

Executes a statement on a host of host_type 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 MySQL supported types 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.

Definition at line 313 of file cluster.hpp.

ExecuteBulk() [2/2]

template<typename Container >

StatementResultSet storages::mysql::Cluster::ExecuteBulk	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		const Query &	query,
		const Container &	params
	)		const

Executes a statement on a host of host_type with provided CommandControl. 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 MySQL supported types 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.

struct SampleRow final {
  std::string title;
  int amount;
  std::chrono::system_clock::time_point created;
};
 
void PerformExecuteBulk(const Cluster& cluster,
                        std::chrono::milliseconds timeout,
                        const std::vector<SampleRow>& rows) {
  const auto bulk_insertion_result =
      cluster
          .ExecuteBulk(CommandControl{timeout}, ClusterHostType::kPrimary,
                       "INSERT INTO SampleTable(title, amount, created) "
                       "VALUES(?, ?, ?)",
                       rows)
          .AsExecutionResult();
 
  // When performing a multi insert prepared statement, mysql_stmt_insert_id()
  // will return the value of the first row.
  EXPECT_EQ(bulk_insertion_result.last_insert_id, 1);
  EXPECT_EQ(bulk_insertion_result.rows_affected, rows.size());
}

Definition at line 320 of file cluster.hpp.

ExecuteBulkMapped() [1/2]

template<typename MapTo , typename Container >

StatementResultSet storages::mysql::Cluster::ExecuteBulkMapped	(	ClusterHostType	host_type,
		const Query &	query,
		const Container &	params
	)		const

Executes a statement on a host of host_type 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 MySQL supported types 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.

Definition at line 333 of file cluster.hpp.

ExecuteBulkMapped() [2/2]

template<typename MapTo , typename Container >

StatementResultSet storages::mysql::Cluster::ExecuteBulkMapped	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		const Query &	query,
		const Container &	params
	)		const

Executes a statement on a host of host_type with provided CommandControl, 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 MySQL supported types 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.

struct SampleUserStruct final {
  std::string name;
  std::string description;
  int amount;
};
 
struct SampleRow final {
  std::string title;
  int amount;
  std::chrono::system_clock::time_point created;
};
 
SampleRow Convert(const SampleUserStruct& data, convert::To<SampleRow>) {
  return {
      fmt::format("{} {}", data.name, data.description),  // title
      data.amount,                                        // amount
      std::chrono::system_clock::now()                    // created
  };
}
 
void PerformExecuteBulkMapped(const Cluster& cluster,
                              std::chrono::milliseconds timeout,
                              const std::vector<SampleUserStruct>& data) {
  const auto bulk_insertion_result =
      cluster
          .ExecuteBulkMapped<SampleRow>(
              CommandControl{timeout}, ClusterHostType::kPrimary,
              "INSERT INTO SampleTable(title, amount, created) "
              "VALUES(?, ?, ?)",
              data)
          .AsExecutionResult();
 
  // When performing a multi insert prepared statement, mysql_stmt_insert_id()
  // will return the value of the first row.
  EXPECT_EQ(bulk_insertion_result.last_insert_id, 1);
  EXPECT_EQ(bulk_insertion_result.rows_affected, data.size());
}

Definition at line 340 of file cluster.hpp.

ExecuteCommand() [1/2]

CommandResultSet storages::mysql::Cluster::ExecuteCommand	(	ClusterHostType	host_type,
		const Query &	command
	)		const

Executes a command on host of type host_type over plan-text protocol, with default deadline.

This method is intended to be used for statements that cannot be prepared or as an escape hatch from typed parsing if you really need to, but such use is neither recommended nor optimized for.

ExecuteCommand() [2/2]

CommandResultSet storages::mysql::Cluster::ExecuteCommand	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		const Query &	command
	)		const

Executes a command on host of type host_type over plan-text protocol, with provided CommandControl.

This method is intended to be used for statements that cannot be prepared or as an escape hatch from typed parsing if you really need to, but such use is neither recommended nor optimized for.

void PrepareExampleTable(const Cluster& cluster) {
  constexpr std::chrono::milliseconds kTimeout{1750};
  cluster.ExecuteCommand(ClusterHostType::kPrimary,
                         "DROP TABLE IF EXISTS SampleTable");
  cluster.ExecuteCommand(CommandControl{kTimeout}, ClusterHostType::kPrimary,
                         "CREATE TABLE SampleTable("
                         "Id INT PRIMARY KEY AUTO_INCREMENT,"
                         "title TEXT NOT NULL,"
                         "amount INT NOT NULL,"
                         "created TIMESTAMP NOT NULL)");
}

ExecuteDecompose() [1/2]

template<typename T >

StatementResultSet storages::mysql::Cluster::ExecuteDecompose	(	ClusterHostType	host_type,
		const Query &	query,
		const T &	row
	)		const

Executes a statement on a host of host_type 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 MySQL supported types for better understanding of T requirements.

UINVARIANTs on params count mismatch, doesn't validate types.

Definition at line 296 of file cluster.hpp.

ExecuteDecompose() [2/2]

template<typename T >

StatementResultSet storages::mysql::Cluster::ExecuteDecompose	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		const Query &	query,
		const T &	row
	)		const

Executes a statement on a host of host_type with provided CommandControl.

Basically an alias for Execute(command_control, 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 MySQL supported types for better understanding of T requirements.

UINVARIANTs on params count mismatch, doesn't validate types.

struct SampleRow final {
  std::string title;
  int amount;
  std::chrono::system_clock::time_point created;
};
 
void PerformExecuteDecompose(const Cluster& cluster,
                             std::chrono::milliseconds timeout,
                             const SampleRow& row) {
  const auto insertion_result =
      cluster
          .ExecuteDecompose(CommandControl{timeout}, ClusterHostType::kPrimary,
                            "INSERT INTO SampleTable(title, amount, created) "
                            "VALUES(?, ?, ?)",
                            row)
          .AsExecutionResult();
 
  EXPECT_EQ(insertion_result.rows_affected, 1);
  EXPECT_EQ(insertion_result.last_insert_id, 1);
}

Definition at line 303 of file cluster.hpp.

GetCursor() [1/2]

template<typename T , typename... Args>

CursorResultSet< T > storages::mysql::Cluster::GetCursor	(	ClusterHostType	host_type,
		std::size_t	batch_size,
		const Query &	query,
		const Args &...	args
	)		const

Executes a statement with default deadline on a host of host_type, filling statements placeholders with args..., and returns a read-only cursor which fetches batch_count rows in each next fetch request. See MySQL supported types for better understanding of Args requirements.

Note

Deadline is processing-wide, not just for initial cursor creation.

UINVARIANTs on params count mismatch, doesn't validate types.

Definition at line 353 of file cluster.hpp.

GetCursor() [2/2]

template<typename T , typename... Args>

CursorResultSet< T > storages::mysql::Cluster::GetCursor	(	OptionalCommandControl	command_control,
		ClusterHostType	host_type,
		std::size_t	batch_size,
		const Query &	query,
		const Args &...	args
	)		const

Executes a statement with provided CommandControl on a host of host_type, filling statements placeholders with args..., and returns a read-only cursor which fetches batch_count rows in each next fetch request. See MySQL supported types for better understanding of Args requirements.

Note

Deadline is processing-wide, not just for initial cursor creation.

UINVARIANTs on params count mismatch, doesn't validate types.

struct SampleRow final {
  std::string title;
  int amount;
  std::chrono::system_clock::time_point created;
};
 
void PerformGetCursor(const Cluster& cluster,
                      std::chrono::milliseconds timeout) {
  const std::size_t batch_size = 5;
  const auto deadline = engine::Deadline::FromDuration(timeout);
 
  std::int64_t total = 0;
  cluster
      .GetCursor<SampleRow>(CommandControl{timeout},
                            ClusterHostType::kSecondary, batch_size,
                            "SELECT title, amount, created FROM SampleTable")
      .ForEach([&total](SampleRow&& row) { total += row.amount; }, deadline);
 
  // There are 9 rows in the table with amount from 1 to 9
  EXPECT_EQ(total, 45);
}

Definition at line 361 of file cluster.hpp.

---

The documentation for this class was generated from the following file:

• userver/storages/mysql/cluster.hpp