Session operations

Functions
mysqlx_client_t *	mysqlx_get_client_from_url (const char *conn_string, const char *client_opts, mysqlx_error_t **error)
	Create a client instance using connection string or URL and a client options JSON. More...
mysqlx_client_t *	mysqlx_get_client_from_options (mysqlx_session_options_t *opt, mysqlx_error_t **error)
	Create a client pool using session configuration data. More...
void	mysqlx_client_close (mysqlx_client_t *client)
	Close the client pool and all sessions created by them. More...
mysqlx_session_t *	mysqlx_get_session (const char *host, int port, const char *user, const char *password, const char *database, mysqlx_error_t **error)
	Create a new session. More...
mysqlx_session_t *	mysqlx_get_session_from_url (const char *conn_string, mysqlx_error_t **error)
	Create a session using connection string or URL. More...
mysqlx_session_t *	mysqlx_get_session_from_options (mysqlx_session_options_t *opt, mysqlx_error_t **error)
	Create a session using session configuration data. More...
void	mysqlx_session_close (mysqlx_session_t *session)
	Close the session. More...
int	mysqlx_session_valid (mysqlx_session_t *sess)
	Check the session validity. More...
mysqlx_result_t *	mysqlx_get_schemas (mysqlx_session_t *sess, const char *schema_pattern)
	Get a list of schemas. More...
mysqlx_schema_t *	mysqlx_get_schema (mysqlx_session_t *sess, const char *schema_name, unsigned int check)
	Get a schema object and optionally check if it exists on the server. More...
mysqlx_result_t *	mysqlx_get_tables (mysqlx_schema_t *schema, const char *table_pattern, int get_views)
	Get a list of tables and views in a schema. More...
mysqlx_table_t *	mysqlx_get_table (mysqlx_schema_t *schema, const char *tab_name, unsigned int check)
	Get a table object and optionally check if it exists in the schema. More...
mysqlx_result_t *	mysqlx_get_collections (mysqlx_schema_t *schema, const char *col_pattern)
	Get a list of collections in a schema. More...
mysqlx_collection_t *	mysqlx_get_collection (mysqlx_schema_t *schema, const char *col_name, unsigned int check)
	Get a collection object and optionally check if it exists in the schema. More...
int	mysqlx_transaction_begin (mysqlx_session_t *sess)
	Begin a transaction for the session. More...
int	mysqlx_transaction_commit (mysqlx_session_t *sess)
	Commit a transaction for the session. More...
int	mysqlx_transaction_rollback (mysqlx_session_t *sess)
	Roll back a transaction for the session. More...
const char *	mysqlx_savepoint_set (mysqlx_session_t *sess, const char *name)
	Create savepoint inside transaction. More...
int	mysqlx_savepoint_release (mysqlx_session_t *sess, const char *name)
	Release savepoint created by mysqlx_savepoint_set(). More...
int	mysqlx_rollback_to (mysqlx_session_t *sess, const char *name)
	Roll back to savepoint created by mysqlx_savepoint_set(). More...
mysqlx_session_options_t *	mysqlx_session_options_new ()
	Allocate a new session configuration data object. More...
void	mysqlx_free_options (mysqlx_session_options_t *opt)
	Free a session configuration data object. More...
int	mysqlx_session_option_set (mysqlx_session_options_t *opth,...)
	Set session configuration options. More...
int	mysqlx_session_option_get (mysqlx_session_options_t *opth, int opt,...)
	Read session configuration options. More...

Detailed Description

Function Documentation

mysqlx_get_client_from_url()

mysqlx_client_t * mysqlx_get_client_from_url	(	const char *	conn_string,
		const char *	client_opts,
		mysqlx_error_t **	error
	)

Create a client instance using connection string or URL and a client options JSON.

Connection sting has the form "user:pass@host:port/?option&option", valid URL is like a connection string with a mysqlx:// prefix. Host is specified as either DNS name, IPv4 address of the form "nn.nn.nn.nn" or IPv6 address of the form "[nn:nn:nn:...]".

Possible connection options are:

• ssl-mode : TLS connection mode
• ssl-ca=path : path to a PEM file specifying trusted root certificates

Specifying ssl-ca option implies ssl-mode=VERIFY_CA.

Client options are expressed in a JSON string format. Here is an example:

{ "pooling": {
    "enabled": true,
    "maxSize": 25,
    "queueTimeout": 1000,
    "maxIdleTime": 5000}
}

All options are defined under a document with key vale "pooling". Inside the document, the available options are these:

• enabled : boolean value that enable or disable connection pooling. If disabled, session created from pool are the same as created directly without client handle. Enabled by default.
• maxSize : integer that defines the max pooling sessions possible. If uses tries to get session from pool when maximum sessions are used, it will wait for an available session untill queueTimeout. Defaults to 25.
• queueTimeout : integer value that defines the time, in milliseconds, that client will wait to get an available session. By default it doesn't timeouts.
• maxIdleTime : integer value that defines the time, in milliseconds, that an available session will wait in the pool before it is removed. By default it doesn't cleans sessions.

Parameters

	conn_string	connection string
	client_opts	client options in the form of a JSON string.
[out]	error	if error happens during connect the error object is returned through this parameter

Returns

client handle if client could be created, otherwise NULL is returned and the error information is returned through the error output parameter.

Note

The client returned by the function must be properly closed using mysqlx_client_close().

If an error object returned through the output parameter it must be freed using mysqlx_free().

mysqlx_get_client_from_options()

mysqlx_client_t * mysqlx_get_client_from_options	(	mysqlx_session_options_t *	opt,
		mysqlx_error_t **	error
	)

Create a client pool using session configuration data.

Client options are expressed in a JSON string format. Here is an example:

{ "pooling": {
    "enabled": true,
    "maxSize": 25,
    "queueTimeout": 1000,
    "maxIdleTime": 5000}
}

All options are defined under a document with key vale "pooling". Inside the document, the available options are these:

• enabled : boolean value that enable or disable connection pooling. If disabled, session created from pool are the same as created directly without client handle. Enabled by default.
• maxSize : integer that defines the max pooling sessions possible. If uses tries to get session from pool when maximum sessions are used, it will wait for an available session untill queueTimeout. Defaults to 25.
• queueTimeout : integer value that defines the time, in milliseconds, that client will wait to get an available session. By default it doesn't timeouts.
• maxIdleTime : integer value that defines the time, in milliseconds, that an available session will wait in the pool before it is removed. By default it doesn't cleans sessions.

Parameters

	opt	handle to client configuration data
[out]	error	if error happens during connect the error object is returned through this parameter

Returns

client handle if client could be created, otherwise NULL is returned and the error information is returned through the error output parameter.

Note

The client returned by the function must be properly closed using mysqlx_client_close().

If an error object returned through the output parameter it must be freed using mysqlx_free().

mysqlx_client_close()

void mysqlx_client_close

(

mysqlx_client_t *

client

)

Close the client pool and all sessions created by them.

This function must be called by the user to prevent memory leaks. Closing client closes all sessions created by this client.
Sessions created by this client are closed, but their resources are not freed. mysqlx_session_close() has to be called to prevent memory leaks.

After a call to this function the given client handle becomes invalid. Any attempt to use the handle after this, results in undefined behavior.

Parameters

client

client handle

mysqlx_get_session()

mysqlx_session_t * mysqlx_get_session	(	const char *	host,
		int	port,
		const char *	user,
		const char *	password,
		const char *	database,
		mysqlx_error_t **	error
	)

Create a new session.

Parameters

	host	server host DNS name, IPv4 address or IPv6 address
	port	port number
	user	user name
	password	password
	database	default database name
[out]	error	if error happens during connect the error object is returned through this parameter

Returns

session handle if session could be created, otherwise NULL is returned and the error information is returned through output error parameter.

Note

The session returned by the function must be properly closed using mysqlx_session_close().

This function always establishes connection with SSL enabled

If an error object returned through the output parameter it must be freed using mysqlx_free().

mysqlx_get_session_from_url()

mysqlx_session_t * mysqlx_get_session_from_url	(	const char *	conn_string,
		mysqlx_error_t **	error
	)

Create a session using connection string or URL.

Parameters

	conn_string	connection string
[out]	error	if error happens during connect the error object is returned through this parameter

Returns

session handle if session could be created, otherwise NULL is returned and the error information is returned through the error output parameter.

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 #MYSQLX_OPT_SSL_MODE; the value is a case insensitive name of the SSL mode
• ssl-ca=... : see #MYSQLX_OPT_SSL_CA
• auth=...: see #MYSQLX_OPT_AUTH; the value is a case insensitive name of the authentication method
• connect-timeout=...: see #MYSQLX_OPT_CONNECT_TIMEOUT
• connection-attributes=[...] : see #MYSQLX_OPT_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 #MYSQLX_OPT_TLS_VERSIONS
• tls-ciphersuites=[...] : see #MYSQLX_OPT_TLS_CIPHERSUITES
• compression=... : see #MYSQLX_OPT_COMPRESSION
• compression-algorithms=[...] : see #MYSQLX_OPT_COMPRESSION_ALGORITHMS

Note

The session returned by the function must be properly closed using mysqlx_session_close().

If an error object returned through the output parameter it must be freed using mysqlx_free().

mysqlx_get_session_from_options()

mysqlx_session_t * mysqlx_get_session_from_options	(	mysqlx_session_options_t *	opt,
		mysqlx_error_t **	error
	)

Create a session using session configuration data.

Parameters

	opt	handle to session configuration data
[out]	error	if error happens during connect the error object is returned through this parameter

Returns

session handle if session could be created, otherwise NULL is returned and the error information is returned through the error output parameter.

Note

The session returned by the function must be properly closed using mysqlx_session_close().

If an error object returned through the output parameter it must be freed using mysqlx_free().

mysqlx_session_close()

void mysqlx_session_close

(

mysqlx_session_t *

session

)

Close the session.

This function must be called by the user to prevent memory leaks. Closing session frees all related resources, including those allocated by statements and results belonging to the session.

After a call to this function the given session handle becomes invalid. Any attempt to use the handle after this, results in undefined behavior.

Parameters

session

session handle

mysqlx_session_valid()

int mysqlx_session_valid

(

mysqlx_session_t *

sess

)

Check the session validity.

Parameters

sess	session handle

Returns

1 - if the session is valid, 0 - if the session is not valid

Note

The function checks only the internal session status without communicating with server(s).

This function cannot be called for a session that was closed, because in this case the session handle itself is invalid and cannot be used in API calls.

mysqlx_get_schemas()

mysqlx_result_t * mysqlx_get_schemas	(	mysqlx_session_t *	sess,
		const char *	schema_pattern
	)

Get a list of schemas.

The result is returned as a set of rows with one column containing schema name. The rows can be read with functions such as mysqlx_row_fetch_one(), mysqlx_store_result() etc.

Parameters

sess	session handle
schema_pattern	schema name pattern to search, using "%" as a wildcard character; if this parameter is NULL then all schemas will be returned.

Returns

handle to the result with rows containing schema names. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_get_schema()

mysqlx_schema_t * mysqlx_get_schema	(	mysqlx_session_t *	sess,
		const char *	schema_name,
		unsigned int	check
	)

Get a schema object and optionally check if it exists on the server.

Parameters

sess	session handle
schema_name	name of the schema
check	flag to verify if the schema with the given name exists on the server (1 - check, 0 - do not check)

Returns

handle to the schema object or NULL if an error occurred or the schema does not exist on the server

Note

Performing existence check involves communication with server(s). Without the check, this operation is executed locally. It is then possible to create a handle to a non-existent schema. Attempt to use such a handle later would eventually trigger an error.

mysqlx_get_tables()

mysqlx_result_t * mysqlx_get_tables	(	mysqlx_schema_t *	schema,
		const char *	table_pattern,
		int	get_views
	)

Get a list of tables and views in a schema.

The result is returned as a set of rows with two columns. The first column contains table/view name, the second column contains object type, either "TABLE" or "VIEW". The rows can be read with functions such as mysqlx_row_fetch_one(), mysqlx_store_result() etc.

Parameters

schema	schema handle
table_pattern	table name pattern to search, using "%" as a wildcard character; if this parameter is NULL then all tables/views in the given schema will be returned.
get_views	flag specifying whether view names should be included into the result. 0 - do not show views (only table names are in the result), 1 - show views (table and view names are in the result)

Returns

handle to the result with rows containing table/view names. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

Note

this function does not return names of tables that represent collections, use mysqlx_get_collections() function for getting collections.

mysqlx_get_table()

mysqlx_table_t * mysqlx_get_table	(	mysqlx_schema_t *	schema,
		const char *	tab_name,
		unsigned int	check
	)

Get a table object and optionally check if it exists in the schema.

Parameters

schema	schema handle
tab_name	name of the table
check	flag to verify if the table with the given name exists in the schema (1 - check, 0 - do not check)

Returns

handle to the table or NULL if an error occurred or the table does not exist in the schema

Note

Performing existence check involves communication with server(s). Without the check, this operation is executed locally. It is then possible to create a handle to a non-existent table. Attempt to use such a handle later would eventually trigger an error.

mysqlx_get_collections()

mysqlx_result_t * mysqlx_get_collections	(	mysqlx_schema_t *	schema,
		const char *	col_pattern
	)

Get a list of collections in a schema.

The result is returned as a set of rows with two columns. The first column contains collection name and the second column contains string "COLLECTION". The rows can be read with functions such as mysqlx_row_fetch_one(), mysqlx_store_result() etc.

Parameters

schema	handle
col_pattern	collection name pattern to search, using "%" as a wildcard character; if this parameter is NULL then all collections in the given schema will be returned.

Returns

handle to the result with rows containing collection names. NULL is returned only in case of an error. The error details can be obtained using mysqlx_error() function

mysqlx_get_collection()

mysqlx_collection_t * mysqlx_get_collection	(	mysqlx_schema_t *	schema,
		const char *	col_name,
		unsigned int	check
	)

Get a collection object and optionally check if it exists in the schema.

Parameters

schema	schema handle
col_name	name of the collection
check	flag to verify if the collection with the given name exists in the schema (1 - check, 0 - do not check)

Returns

handle to the collection or NULL if an error occurred or the collection does not exist in the schema

Note

Performing existence check involves communication with server(s). Without the check, this operation is executed locally. It is then possible to create a handle to a non-existent collection. Attempt to use such a handle later would eventually trigger an error.

mysqlx_transaction_begin()

int mysqlx_transaction_begin

(

mysqlx_session_t *

sess

)

Begin a transaction for the session.

Parameters

sess	session handle

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

a statement will belong to the transaction when it is actually executed after the transaction began (and before it is committed or rolled back) even if this statement was created before mysqlx_transaction_begin() call

mysqlx_transaction_commit()

int mysqlx_transaction_commit

(

mysqlx_session_t *

sess

)

Commit a transaction for the session.

Parameters

sess	session handle

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

This will commit all statements that were executed as part of this transaction, regardless of when the statements were created (see mysqlx_transaction_begin()).

mysqlx_transaction_rollback()

int mysqlx_transaction_rollback

(

mysqlx_session_t *

sess

)

Roll back a transaction for the session.

Parameters

sess	session handle

Returns

RESULT_OK - on success; RESULT_ERROR - on error

Note

This will roll back all statements that were executed as part of this transaction, regardless of when the statements were created (see mysqlx_transaction_begin()).

mysqlx_savepoint_set()

const char * mysqlx_savepoint_set	(	mysqlx_session_t *	sess,
		const char *	name
	)

Create savepoint inside transaction.

Parameters

sess	session handle.
name	savepoint name (NULL for automatically generated one)

Returns

savepoint name

Note

Savepoints are created inside transaction! Later, you can roll back the transaction to a created savepoint using mysqlx_rollback_to(). If the current transaction has a savepoint with the same name, the old savepoint is deleted and a new one is set.

mysqlx_savepoint_release()

int mysqlx_savepoint_release	(	mysqlx_session_t *	sess,
		const char *	name
	)

Release savepoint created by mysqlx_savepoint_set().

Parameters

sess	session handle
name	savepoint name to be released

Returns

RESULT_OK - savepoint exists and is released; RESULT_ERROR - on error

mysqlx_rollback_to()

int mysqlx_rollback_to	(	mysqlx_session_t *	sess,
		const char *	name
	)

Roll back to savepoint created by mysqlx_savepoint_set().

Parameters

sess	session handle.
name	savepoint name.

Returns

RESULT_OK - savepoint exists and is released; RESULT_ERROR - on error.

mysqlx_session_options_new()

mysqlx_session_options_t * mysqlx_session_options_new

(

)

Allocate a new session configuration data object.

Returns

handle to the newly allocated configuration data

Note

The allocated object must be eventually freed by mysqlx_free() to prevent memory leaks

mysqlx_free_options()

void mysqlx_free_options

(

mysqlx_session_options_t *

opt

)

Free a session configuration data object.

Parameters

opt	handle to sessin configuartion data object that has to be freed

Note

This function is DEPRECATED. Use mysqlx_free() instead.

mysqlx_session_option_set()

int mysqlx_session_option_set	(	mysqlx_session_options_t *	opth,
			...
	)

Set session configuration options.

Parameters

opth	handle to session configuration data object
...	variable parameters list consisting of (option, value) pairs terminated by PARAM_END.

Returns

RESULT_OK if option was successfully set; RESULT_ERROR is set otherwise (use mysqlx_error() to get the error information)

The variable parameter list is of the form

OPT_O1(val1), OPT_O2(val2), ..., OPT_On(valn), PARAM_END

or, equivalently,

MYSQLX_OPT_O1, val1, ..., MYSQLX_OPT_On, valn, PARAM_END

Possible options are defined by enumeration mysqlx_opt_type_t. Type of option value vali (number, string, etc.) must match the option MYSQLX_OPT_Oi, otherwise this value along with all the sequential options and values are most likely to be corrupted.

mysqlx_session_option_get()

int mysqlx_session_option_get	(	mysqlx_session_options_t *	opth,
		int	opt,
			...
	)

Read session configuration options.

Parameters

	opth	handle to session configuration data object
	opt	option whose value to read (see mysqlx_opt_type_t)
[out]	...	pointer to a buffer where to return the requested value

TODO: Point to documentation explaining what data is returned for each option.

Returns

RESULT_OK if option was successfully read; RESULT_ERROR is set otherwise (use mysqlx_error() to get the error information)

Note

When reading string option values to a bufer, user is responsible for providing a large enough buffer. No overrun checks are done when copying data to the buffer.

For failover configurations with multiple hosts this function will return only the last added host name. Same is true for the port or the priority associated with this host name.