|
MySQL Connector/C++ 9.4.0
MySQL connector library for C and C++ applications
|
Connector/C++ implements the X DevAPI, as described in the X DevAPI User Guide. The X DevAPI allows one to work with the document store of MySQL Server 8 or later, communicating over the X protocol. It is also possible to execute plain SQL queries using this API.
To get started, check out some of the main X DevAPI classes:
mysqlx::Session object. Keep in mind that mysqlx::Session is not thread safe!mysqlx::Collection or a mysqlx::Table object using methods `getCollection()` or `getTable()` of a mysqlx::Schema object obtained from the session.mysqlx::Collection or mysqlx::Table class, such as `find()`. They are executed with the `execute()` method.mysqlx::DocResult or mysqlx::RowResult instances returned from execute() method. Method `fetchOne()` fetches the next item (a document or a row) from the result until there are no more items left. Method `fetchAll()` can fetch all items at once and store them in an STL container.mysqlx::DbDoc and mysqlx::Row instances, respectively.A more complete example of code that access MySQL Document Store using the X DevAPI is presented below. See also the list of X DevAPI classes.
The following Connector/C++ application connects to a MySQL Server over X protocol, creates a document collection, adds a few documents to it, queries the collection and displays the result. The sample code can be found in file testapp/devapi_test.cc in the source distribution of Connector/C++. See Using Connector/C++ for instructions on how to build the sample code.
Code which uses X DevAPI should include the <mysqlx/xdevapi.h> header. The API is declared within the mysqlx namespace:
To create a mysqlx::Session object pass a connection string in URI format such as "mysqlx://mike:s3cr3t!@localhost:13009". It specifies the host and port of the MySQL Server (port can be skipped in which case the default port will be used) and the MySQL account credentials.
If the session could not be established the mysqlx::Session constructor throws an error derived from mysqlx::Error class (which also derives from std::exception). Otherwise the session is ready to be used once created.
mysqlx::Session constructor uses its arguments to create a mysqlx::SessionSettings instance – see documentation of that class for possible arguments to the constructor. Enumeration mysqlx::SessionOption defines all session options recognized by the connector.Next a test schema is created and a c1 collection within that schema. They are represented by mysqlx::Schema and mysqlx::Collection objects, respectively:
The true parameter to the `Session::createSchema()`/`Schema::createCollection()` method specifies that the schema/collection should be re-used if it already exists (rather than throwing an error which is the default behavior).
mysqlx::Collection object directly, without explicitly creating a mysqlx::Schema instance: Before adding documents to the collection, all the existing documents are removed first using the `Collection::remove()` method. The argument to this method is an expression which selects documents to be removed, in this case expression "true" selects all documents:
Note that the remove() method returns an operation that must be explicitly executed to take effect. When executed, operation returns a result (ignored here; the results are used later).
To insert documents use the `Collection::add()` method. Documents are described by JSON strings. Note that double quotes are required around field names and they must be escaped inside C strings unless the R"(...)" raw string literal syntax is used as in the example below. Note also how internal code block is used to delete the result when it is no longer needed:
Result of the add() operation is stored in the add variable to be able to read identifiers of the inserted documents that were assigned by the server. They are returned by the getGeneratedIds() method of the mysqlx::Result class.
"_id" field – in that case the value of the "_id" field is used as document's identifier. These explicit identifiers are not reported by getGeneratedIds() method.add() calls as follows: coll.add(doc1).add(doc2)...add(docN).execute(). It is also possible to pass several documents to a single add() call: coll.add(doc1, ..., docN).execute(). Another option is to pass to Collection::add() an STL container with several documents.To query documents of a collection use the `Collection::find()` method which takes a Boolean expression that selects documents as its argument:
The result of the find() operation is stored in a variable of type mysqlx::DocResult which gives access to the returned documents that satisfy the selection criteria. These documents can be iterated using a range-for loop:
Given a mysqlx::DbDoc object it is possible to iterate over its fields as follows:
Note how DbDoc::operator[] is used to access values of document fields:
The value of a field is automatically converted to a corresponding C++ type. If the C++ type does not match the type of the field value, conversion error is thrown.
Fields which are sub-documents can be converted to the mysqlx::DbDoc type. The following code demonstrates how to process the "date" field which is a sub-document. Methods `DbDoc::hasField()` and `DbDoc::fieldType()` are used to examine existence and type of a field within a document.
In case of arrays currently no conversion to C++ types is defined. However, individual elements of an array value can be accessed using operator[] or they can be iterated using a range-for loop.
Any errors thrown by Connector/C++ derive from the mysqlx::Error type and can be processed as follows:
The complete code of the example is presented below:
A sample output produced by this code: