Session Class Reference

Represents a session which gives access to data stored in a data store. More...

Public Member Functions
	Session (SessionSettings settings)
	Create a session specified by a SessionSettings object.
template<typename... T>
	Session (T...options)
	Create a session using given session settings. More...
Schema	createSchema (const string &name, bool reuse=false)
	Create a new schema. More...
Schema	getSchema (const string &name, bool check_exists=false)
	Return an object representing a schema with the given name. More...
Schema	getDefaultSchema ()
	Get the default schema specified when the session was created.
string	getDefaultSchemaName ()
	Get the name of the default schema specified when the session was created.
SchemaList	getSchemas ()
	Get a list of all database schemas. More...
void	dropSchema (const string &name)
	Drop the named schema. More...
SqlStatement	sql (const string &query)
	Return an operation which executes an arbitrary SQL statement. More...
void	startTransaction ()
	Start a new transaction. More...
void	commit ()
	Commit opened transaction, if any. More...
void	rollback ()
	Roll back opened transaction, if any. More...
void	rollbackTo (const string &savepoint)
	Roll back opened transaction to specified savepoint. More...
string	setSavepoint (const string &savepoint)
	Sets a named transaction savepoint with a name as identifier. More...
string	setSavepoint ()
	Creats a transaction savepoint with a generated name as identifier. More...
void	releaseSavepoint (const string &savepoint)
	Releases savepoint previously added by setSavepoint(). More...
void	close ()
	Close this session. More...

Detailed Description

Represents a session which gives access to data stored in a data store.

A Session object can be created from a connection string, from SessionSettings or by directly specifying a host name, TCP/IP port and user credentials. Once created, a session is ready to be used. Session destructor closes the session and cleans up after it.

If it is not possible to create a valid session for some reason, errors are thrown from session constructor.

Several hosts can be specified by session creation parameters. In that case a failed connection to one of the hosts triggers a fail-over attempt to connect to a different host in the list. Only if none of the hosts could be contacted, session creation fails.

The fail-over logic tries hosts in the order in which they are specified in session settings unless explicit priorities are assigned to the hosts. In that case hosts are tried in the decreasing priority order and for hosts with the same priority the order in which they are tired is random.

Once a valid session is created using one of the hosts, the session is bound to that host and never re-connected again. If the connection gets broken, the session fails without making any other fail-over attempts. The fail-over logic is executed only when establishing a new session.

Note

A Session object should be used by at most one thread at a time. It is not safe to call its methods by several threads simultaneously. It is responsibility of the user to ensure this using a synchronization mechanism such as mutexes.

Constructor & Destructor Documentation

Session()

Session ( T...  options )

inline

Create a session using given session settings.

This constructor forwards arguments to a SessionSettings constructor. Thus all forms of specifying session options are also directly available in Session constructor.

Examples:

Session from_uri("mysqlx://user:pwd@host:port/db?ssl-mode=disabled");
 
 
Session from_options("host", port, "user", "pwd", "db");
 
Session from_option_list(
  SessionOption::USER, "user",
  SessionOption::PWD,  "pwd",
  SessionOption::HOST, "host",
  SessionOption::PORT, port,
  SessionOption::DB,   "db",
  SessionOption::SSL_MODE, SSLMode::DISABLED
);

See also

SessionSettings

Member Function Documentation

createSchema()

Schema createSchema ( const string &  name, bool  reuse = false  )

inline

Create a new schema.

Returns the created schema. Set reuse flag to true to return an already existing schema with the same name. Otherwise, an attempt to create a schema which already exists throws an error.

getSchema()

Schema getSchema ( const string &  name, bool  check_exists = false  )

inline

Return an object representing a schema with the given name.

To check if the schema actually exists in the database set check_existence flag to true. Otherwise the returned object can refer to a non-existing schema. An attempt to use such a non-existing schema in a database operation throws an error.

Note

Checking the existence of a schema involves communication with the server. If check_exists is false, on the other hand, no I/O is involved when creating a Schema object.

getSchemas()

SchemaList getSchemas ( )

inline

Get a list of all database schemas.

The returned value can be stored in a container that holds Schema objects, such as std::vector<Schema>.

dropSchema()

void dropSchema ( const string &  name )

inline

Drop the named schema.

Error is thrown if the schema doesn't exist,

sql()

SqlStatement sql ( const string &  query )

inline

Return an operation which executes an arbitrary SQL statement.

Call execute() on the returned operation object to execute the statement and get an SqlResult object representing its results. If the SQL statement contains ? placeholders, call bind() to define their values prior to the execution.

Note

Errors related to SQL execution are reported when the statement is executed, not when it is created.

startTransaction()

void startTransaction ( )

inline

Start a new transaction.

Throws error if previously opened transaction is not closed.

commit()

void commit ( )

inline

Commit opened transaction, if any.

Does nothing if no transaction was opened. After committing the transaction is closed.

rollback()

void rollback ( )

inline

Roll back opened transaction, if any.

Does nothing if no transaction was opened. Transaction which was rolled back is closed. To start a new transaction a call to startTransaction() is needed.

rollbackTo()

void rollbackTo ( const string &  savepoint )

inline

Roll back opened transaction to specified savepoint.

It rolls back to savepoint, but transaction remains active. Does nothing if no transaction was opened.

Exceptions

Error

If savepoint doesn't exist or is empty.

setSavepoint() [1/2]

string setSavepoint ( const string &  savepoint )

inline

Sets a named transaction savepoint with a name as identifier.

To use savepoints a transaction has to be started using startTransaction().

Returns

string with savepoint name.

Note

If the current transaction has a savepoint with the same name, the old savepoint is deleted and a new one is set.

setSavepoint() [2/2]

string setSavepoint ( )

inline

Creats a transaction savepoint with a generated name as identifier.

To use savepoints a transaction has to be started using startTransaction().

Returns

string with generated savepoint name.

Note

If the current transaction has a savepoint with the same name, the old savepoint is deleted and a new one is set.

releaseSavepoint()

void releaseSavepoint ( const string &  savepoint )

inline

Releases savepoint previously added by setSavepoint().

Note

Releasing savepoint doesn't affect data.

Exceptions

Error

If savepoint doesn't exist.

close()

void close ( )

inline

Close this session.

After the session is closed, any call to other session's methods throws an error.

---

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

• include/mysqlx/xdevapi.h