MySQL Connector/C++  8.0.12
MySQL connector library for C and C++ applications
Public Member Functions | Static Private Member Functions | List of all members
SessionSettings Class Reference

Represents session options to be passed at session creation time. More...

Public Member Functions

 SessionSettings (const string &uri)
 Create session settings from a connection string. More...
 
 SessionSettings (const std::string &host, unsigned port, const string &user, const char *pwd=NULL, const string &db=string())
 Explicitly specify basic connection settings. More...
 
 SessionSettings (const std::string &host, const string &user, const char *pwd=NULL, const string &db=string())
 Basic settings with the default port. More...
 
 SessionSettings (unsigned port, const string &user, const char *pwd=NULL, const string &db=string())
 Basic settings for a session on the localhost. More...
 
template<typename... R>
 SessionSettings (SessionOption opt, R &&...rest)
 Specify settings as a list of session options. More...
 
Value find (SessionOption opt)
 Find the specified option opt and returns its Value. More...
 
template<typename... R>
void set (SessionOption opt, R &&... rest)
 Set session options. More...
 
void clear ()
 Clear all settings specified so far.
 
void erase (SessionOption opt)
 Remove all settings for the given option opt. More...
 
bool has_option (SessionOption opt)
 Check if option opt was defined.
 

Static Private Member Functions

static const char * option_name (Option opt)
 
static const char * ssl_mode_name (SSL_mode mode)
 
static const char * auth_method_name (Auth_method method)
 

Detailed Description

Represents session options to be passed at session creation time.

SessionSettings can be constructed using a connection string, common connect options (host, port, user, password, database) or with a list of SessionOption constants, each followed by the option value.

Examples:

SessionSettings from_url("mysqlx://user:pwd@host:port/db?ssl-mode=required");
SessionSettings from_options("host", port, "user", "pwd", "db");
SessionSettings from_option_list(
SessionOption::USER, "user",
SessionOption::PWD, "pwd",
SessionOption::HOST, "host",
SessionOption::PORT, port,
SessionOption::DB, "db",
SessionOption::SSL_MODE, SSLMode::REQUIRED
);

The HOST, PORT and SOCKET settings can be repeated to build a list of hosts to be used by the connection fail-over logic when creating a session (see description of Session class). In that case each host can be assigned a priority by setting the PRIORITY option. If priorities are not explicitly assigned, hosts are tried in the order in which they are specified in session settings. If priorities are used, they must be assigned to all hosts specified in the settings.

Constructor & Destructor Documentation

◆ SessionSettings() [1/5]

SessionSettings ( const string uri)
inline

Create session settings from a connection string.

Connection sting has the form

  "user:pass@connection-data/db?option&option"

with optional mysqlx:// prefix.

The connetction-data part is either a single host address or a coma separated list of hosts in square brackets: [host1, host2, ..., hostN]. In the latter case the connection fail-over logic will be used when creating the session.

A single host address is either a DNS host name, an IPv4 address of the form "nn.nn.nn.nn" or an IPv6 address of the form "[nn:nn:nn:...]". On Unix systems a host can be specified as a path to a Unix domain socket - this path must start with / or ..

Characters like / in the connection data, which otherwise have a special meaning inside a connection string, must be represented using percent encoding (e.g., %2F for /). Another option is to enclose a host name or a socket path in round braces. For example, one can write

"mysqlx://(./path/to/socket)/db"

instead of

"mysqlx://.%2Fpath%2Fto%2Fsocket/db"

To specify priorities for hosts in a multi-host settings, use list of pairs of the form (address=host,priority=N). If priorities are specified, they must be given to all hosts in the list.

The optional db part of the connection string defines the default schema of the session.

Possible connection options are:

  • ssl-mode : define SSLMode option to be used
  • ssl-ca=path : path to a PEM file specifying trusted root certificates

◆ SessionSettings() [2/5]

SessionSettings ( const std::string &  host,
unsigned  port,
const string user,
const char *  pwd = NULL,
const string db = string() 
)
inline

Explicitly specify basic connection settings.

Note
Session settings constructed this way request an SSL connection by default.

◆ SessionSettings() [3/5]

SessionSettings ( const std::string &  host,
const string user,
const char *  pwd = NULL,
const string db = string() 
)
inline

Basic settings with the default port.

Note
Session settings constructed this way request an SSL connection by default.

◆ SessionSettings() [4/5]

SessionSettings ( unsigned  port,
const string user,
const char *  pwd = NULL,
const string db = string() 
)
inline

Basic settings for a session on the localhost.

Note
Session settings constructed this way request an SSL connection by default.

◆ SessionSettings() [5/5]

SessionSettings ( SessionOption  opt,
R &&...  rest 
)
inline

Specify settings as a list of session options.

The list of options consist of a SessionOption constant, identifying the option to set, followed by the value of the option.

Example:

SessionSettings from_option_list(
SessionOption::USER, "user",
SessionOption::PWD, "pwd",
SessionOption::HOST, "host",
SessionOption::PORT, port,
SessionOption::DB, "db",
SessionOption::SSL_MODE, SessionSettings::SSLMode::REQUIRED
);

Member Function Documentation

◆ find()

Value find ( SessionOption  opt)
inline

Find the specified option opt and returns its Value.

Throws an error if the given option was not found in the settings.

Note
For option such as HOST, which can repeat several times in the settings, only the last value is reported.

◆ set()

void set ( SessionOption  opt,
R &&...  rest 
)
inline

Set session options.

Accepts a list of one or more SessionOption constants, each followed by the option value. Options specified here are added to the current settings.

Repeated HOST, PORT, SOCKET and PRIORITY options build a list of hosts to be used by the fail-over logic. For other options, if they are set again, the new value overrides the previous setting.

Note
When using HOST, PORT and PRIORITY options to specify a single host, all have to be specified in the same set() call.

◆ erase()

void erase ( SessionOption  opt)
inline

Remove all settings for the given option opt.

Note
For option such as HOST, which can repeat several times in the settings, all occurrences are erased.

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