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::Enum 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.

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=... : see SessionOption::SSL_MODE; the value is a case insensitive name of the SSL mode
• ssl-ca=... : see SessionOption::SSL_CA
• auth=...: see SessionOption::AUTH; the value is a case insensitive name of the authentication method
• connect-timeout=...: see SessionOption::CONNECT_TIMEOUT
• connection-attributes=[...] : see SessionOption::CONNECTION_ATTRIBUTES but the key-value pairs are not given by a JSON document but as a list;
  Examples:
  "mysqlx://user@host?connection-attributes=[foo=bar,qux,baz=]" - specify additional attributes to be sent
  "mysqlx://user@host?connection-attributes=false" - send no connection attributes
  "mysqlx://user@host?connection-attributes=true" - send default connection attributes
  "mysqlx://user@host?connection-attributes=[]" - the same as setting to true
"mysqlx://user@host?connection-attributes" - the same as setting to true
  
• tls-versions=[...] : see SessionOption::TLS_VERSIONS
• tls-ciphersuites=[...] : see SessionOption::TLS_CIPHERSUITES
• compression=... : see SessionOption::COMPRESSION
• compression-algorithms=[...] : see SessionOption::COMPRESSION_ALGORITHMS

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::Enum  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.

Returns NULL Value if not found.

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:

• include/mysqlx/devapi/settings.h