MySQL Connector/C++
MySQL connector library for C and C++ applications
Functions
Session operations

Functions

mysqlx_client_tmysqlx_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_tmysqlx_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_tmysqlx_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_tmysqlx_get_session_from_url (const char *conn_string, mysqlx_error_t **error)
 Create a session using connection string or URL. More...
 
mysqlx_session_tmysqlx_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_tmysqlx_get_schemas (mysqlx_session_t *sess, const char *schema_pattern)
 Get a list of schemas. More...
 
mysqlx_schema_tmysqlx_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_tmysqlx_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_tmysqlx_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_tmysqlx_get_collections (mysqlx_schema_t *schema, const char *col_pattern)
 Get a list of collections in a schema. More...
 
mysqlx_collection_tmysqlx_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_tmysqlx_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_stringconnection string
client_optsclient options in the form of a JSON string.
[out]errorif 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
opthandle to client configuration data
[out]errorif 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
clientclient 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
hostserver host DNS name, IPv4 address or IPv6 address
portport number
useruser name
passwordpassword
databasedefault database name
[out]errorif 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_stringconnection string
[out]errorif 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
opthandle to session configuration data
[out]errorif 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
sessionsession handle

◆ mysqlx_session_valid()

int mysqlx_session_valid ( mysqlx_session_t sess)

Check the session validity.

Parameters
sesssession 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
sesssession handle
schema_patternschema 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
sesssession handle
schema_namename of the schema
checkflag 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
schemaschema handle
table_patterntable 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_viewsflag 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
schemaschema handle
tab_namename of the table
checkflag 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
schemahandle
col_patterncollection 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
schemaschema handle
col_namename of the collection
checkflag 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
sesssession 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
sesssession 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
sesssession 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
sesssession handle.
namesavepoint 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
sesssession handle
namesavepoint 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
sesssession handle.
namesavepoint 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
opthandle 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
opthhandle 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
opthhandle to session configuration data object
optoption 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.