userver: storages::mysql::Cluster Class Reference
Loading...
Searching...
No Matches
storages::mysql::Cluster Class Referencefinal

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

Detailed Description

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

Definition at line 40 of file 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.
 

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_typeHost 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_typeHost 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: