MySQL Connector/C++
MySQL connector library for C and C++ applications
|
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... | |
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 modessl-ca=
path : path to a PEM file specifying trusted root certificatesSpecifying ssl-ca
option implies ssl-mode=VERIFY_CA
.
Client options are expressed in a JSON string format. Here is an example:
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.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 |
mysqlx_client_close()
.mysqlx_free()
. 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:
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.opt | handle to client configuration data | |
[out] | error | if error happens during connect the error object is returned through this parameter |
mysqlx_client_close()
.mysqlx_free()
. 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.
client | client handle |
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.
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 |
mysqlx_session_close()
. mysqlx_free()
. mysqlx_session_t * mysqlx_get_session_from_url | ( | const char * | conn_string, |
mysqlx_error_t ** | error | ||
) |
Create a session using connection string or URL.
conn_string | connection string | |
[out] | error | if error happens during connect the error object is returned through this 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 modessl-ca=...
: see #MYSQLX_OPT_SSL_CA
auth=...
: see #MYSQLX_OPT_AUTH
; the value is a case insensitive name of the authentication methodconnect-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;"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
mysqlx_session_close()
. mysqlx_free()
. mysqlx_session_t * mysqlx_get_session_from_options | ( | mysqlx_session_options_t * | opt, |
mysqlx_error_t ** | error | ||
) |
Create a session using session configuration data.
opt | handle to session configuration data | |
[out] | error | if error happens during connect the error object is returned through this parameter |
mysqlx_session_close()
. mysqlx_free()
. 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.
session | session handle |
int mysqlx_session_valid | ( | mysqlx_session_t * | sess | ) |
Check the session validity.
sess | session handle |
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.
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. |
mysqlx_error()
function 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.
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) |
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.
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) |
mysqlx_error()
functionmysqlx_get_collections()
function for getting collections. 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.
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) |
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.
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. |
mysqlx_error()
function 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.
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) |
int mysqlx_transaction_begin | ( | mysqlx_session_t * | sess | ) |
Begin a transaction for the session.
sess | session handle |
RESULT_OK
- on success; RESULT_ERROR
- on errormysqlx_transaction_begin()
call int mysqlx_transaction_commit | ( | mysqlx_session_t * | sess | ) |
Commit a transaction for the session.
sess | session handle |
RESULT_OK
- on success; RESULT_ERROR
- on errormysqlx_transaction_begin()
). int mysqlx_transaction_rollback | ( | mysqlx_session_t * | sess | ) |
Roll back a transaction for the session.
sess | session handle |
RESULT_OK
- on success; RESULT_ERROR
- on errormysqlx_transaction_begin()
). const char * mysqlx_savepoint_set | ( | mysqlx_session_t * | sess, |
const char * | name | ||
) |
Create savepoint inside transaction.
sess | session handle. |
name | savepoint name (NULL for automatically generated one) |
int mysqlx_savepoint_release | ( | mysqlx_session_t * | sess, |
const char * | name | ||
) |
Release savepoint created by mysqlx_savepoint_set().
sess | session handle |
name | savepoint name to be released |
RESULT_OK
- savepoint exists and is released; RESULT_ERROR
- on error int mysqlx_rollback_to | ( | mysqlx_session_t * | sess, |
const char * | name | ||
) |
Roll back to savepoint created by mysqlx_savepoint_set().
sess | session handle. |
name | savepoint name. |
RESULT_OK
- savepoint exists and is released; RESULT_ERROR
- on error. mysqlx_session_options_t * mysqlx_session_options_new | ( | ) |
Allocate a new session configuration data object.
mysqlx_free()
to prevent memory leaks void mysqlx_free_options | ( | mysqlx_session_options_t * | opt | ) |
Free a session configuration data object.
opt | handle to sessin configuartion data object that has to be freed |
mysqlx_free()
instead. int mysqlx_session_option_set | ( | mysqlx_session_options_t * | opth, |
... | |||
) |
Set session configuration options.
opth | handle to session configuration data object |
... | variable parameters list consisting of (option, value) pairs terminated by PARAM_END . |
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.
int mysqlx_session_option_get | ( | mysqlx_session_options_t * | opth, |
int | opt, | ||
... | |||
) |
Read session configuration options.
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.
RESULT_OK
if option was successfully read; RESULT_ERROR
is set otherwise (use mysqlx_error()
to get the error information)