MySQL Connector/C++ 1.1.11 has been released

Dear MySQL Users,

A new GA (general availability) version of MySQL Connector/C++ has been made available: MySQL Connector/C++ 1.1.11 GA. The MySQL Connector/C++ provides a C++ API for connecting client applications to the MySQL Server 5.5 or newer.

You can download the production release at:

http://dev.mysql.com/downloads/connector/cpp/1.1.html

MySQL Connector C++ (Commercial) will be available for download on the My Oracle Support (MOS) website. This release will be available on eDelivery (OSDC) in next month’s upload cycle.

The MySQL driver for C++ offers an easy to use API derived from JDBC 4.0. MySQL Workbench has used it successfully for years.

We have improved the driver since the last GA release. Please see the documentation and the CHANGES file in the source distribution for a detailed description of bugs that have been fixed. Bug descriptions are also listed below.

Enjoy!

Changes in MySQL Connector/C++ 1.1.11 (2018-04-30, General Availability)

Functionality Added or Changed

  • MySQL Connector/C++ 1.1 now works with both MySQL 5.7 GA and MySQL 8.0 GA servers.
      • Applications can connect to MySQL 8.0 servers using accounts that authenticate using the caching_sha2_password authentication plugin.
      • Applications can connect to MySQL 8.0 servers using unencrypted connections by using the OPT_GET_SERVER_PUBLIC_KEY connection option with a value of true.
      • Connector/C++ 1.1 can be built from source against either MySQL 5.7 and MySQL 8.0 server installations.
      • A new BUNDLE_DEPENDENCIES CMake option is available. If enabled, the external libraries on which Connector/C++ depends at runtime (such as OpenSSL), are packaged together with the connector.
  • For connections to the server made using the legacy JDBC API (that is, not made using X DevAPI or XAPI), Connector/C++ now supports an OPT_GET_SERVER_PUBLIC_KEY connection option that enables requesting the RSA public key from the server. For accounts that use the caching_sha2_password or sha256_password authentication plugin, this key can be used during the connection process for RSA key-pair based password exchange with TLS disabled. This capability requires a MySQL 8.0 GA server, and is supported only for Connector/C++ built using OpenSSL.

Bugs Fixed

    • MySQL Connector/C++ packages now include a BUILDINFO.txt file that contains information about the build environment used to produce the distribution. (Bug #23556661)

On Behalf of the MySQL/ORACLE RE Team
Piotr Obrzut

MySQL Connector/NET 6.10.7 GA has been released

Dear MySQL users,

MySQL Connector/NET 6.10.7 is the fourth GA release with .NET Core
now supporting various connection-string options and MySQL 8.0 server
features.

To download MySQL Connector/NET 6.10.7 GA, see the “Generally Available
(GA) Releases” tab at http://dev.mysql.com/downloads/connector/net/

Changes in MySQL Connector/NET 6.10.7 (2018-04-30, General Availability)

Functionality Added or Changed

* Connections made to MySQL 8.0 (up to and including
version 8.0.3) and compatibility with the new data dictionary are
now supported. For information about the data dictionary, see
MySQL Data Dictionary
(http://dev.mysql.com/doc/refman/8.0/en/data-dictionary.html).

* Support for the caching_sha2_password authentication
plugin through the classic MySQL protocol was added. In addition,
the sha256_password plugin was extended to support authentication
when RSA keys are available through non-secure connections.
Caching SHA-2 pluggable authentication offers faster
authentication than basic SHA-256 authentication.

* Support was added for the new caching_sha2_password
padding mechanism introduced in the MySQL 8.0 release series. The
new padding mechanism is enabled when all of the following
conditions apply:

+ The user account is set with the
caching_sha2_password authentication plugin.

+ SSL is disabled explicitly (SslMode=none).

+ The AllowPublicKeyRetrieval connection option is enabled
(AllowPublicKeyRetrieval=true).  When enabled, the new padding
mechanism is used to encode the password during RSA key
encryption, which applies the correct padding to match the
server.

Bugs Fixed

* Attempting to open the MySQL Web Configuration Tool, with
Connector/NET and MySQL for Visual Studio prerequisites installed
properly, displayed an error message instead of opening the tool.
(Bug #27457398, Bug #88544)

* The ADO.NET Entity Data Model wizard within Visual Studio
closed unexpectedly without producing the data model.  Thanks to
Laurents Meyer for the patch. (Bug #27420311, Bug #89338)

* An exception prevented MySQL.Data.Entity for Entity
Framework 6 from operating as expected. Thanks to Cédric Luthi
for the patch. (Bug #27360520, Bug #89134)

* MySQL Installer could not be installed with NuGet
packages from Microsoft Visual Studio 2015. (Bug #27251839,
Bug #88838)

* With valid references to the DLLs provided, using
DbConfiguration.SetConfiguration(new
MySql.Data.Entity.MySqlEFConfiguration()) to set up the DbContext
threw an exception. (Bug #25185319)

* Attempting to generate an Entity Framework model from a
MySQL 5.7 database using either EF5 or EF6 produced an exception
that prevented the operation from generating the expected model.
(Bug #22173048, Bug #79163)

Nuget packages are available at:

https://www.nuget.org/packages/MySql.Data/6.10.7
https://www.nuget.org/packages/MySql.Web/6.10.7
https://www.nuget.org/packages/MySql.Data.Entity/6.10.7
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore/6.10.7
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore.Design/6.10.7

Enjoy and thanks for the support!

On behalf of the MySQL Release Team,
Nawaz Nazeer Ahamed

MySQL Document Store CRUD Quick Start

This post serves as a quick start guide on how to use the MySQL Document Store with the official Node.js connector. It mainly highlights how easy it is to leverage CRUD-style operations and getting up and running with the X DevAPI.

Before you jump in

Make sure you have Node.js 7.6.0 (or higher) and MySQL 8.0.11 (or higher) installed on your machine.

Setting up your Node.js project

First, using the command line, let’s start by creating a directory for our sample application.

Create a package.json manifest file using the following command:

Next, install the MySQL Node.js Connector from npm:

Starting the MySQL Server

For additional tips on how to install and secure your MySQL server, check the documentation.

  1. Download (if you have not yet) MySQL 8.0
  2. Install and set up a basic (and insecure) server process.

We are using  --initialize-insecure here for the sake of simplicity, however, make sure you use --initialize  (and set up users and privileges accordingly) on production environments and/or “real-world” scenarios.

Connecting to MySQL

Create a new app.js file and write the following code for establishing a connection to the MySQL server using the myproject database/schema (which will be created by default).

The getSession method should return a JavaScript Promise which resolves with a Session object containing the connection details or fails with a Node.js Error if the connection could not be established.

Run the app using the following command:

You should be able to see a Successful server connection  message printed in the console.

Inserting documents

Use the following code to create (or re-use if it exists) documents  collection and add three new documents to it.

The add method returns a Promise which resolves with a Result  object containing details such as:

  • the number of items affected by the operation
  • a list of document _ids auto-generated by the server
  • any server-side warnings resulting from the operation

Add an insertDocuments call in the existing main function like the following:

Running the app should yield the following output:

Retrieving all documents

You can use the following code to retrieve all the existing documents in the collection.

To collect and process records from the result set, you should provide a callback in the execute method.

Use the findDocuments method in the main function.

Finding documents with a given criteria

You can narrow down the results by specifying a query criteria like the following:

The result set will now include just the documents containing 'a': 3.

Updating documents

To modify an existing document i.e. updating specific properties or adding new ones, you can also provide a criteria (or true to modify all) for the operation.

Update the main function to use the updateDocument method like the following:

Removing documents from a collection can also be done based on a given criteria (or true  to remove all). The following code removes the document where the field a is greater than 2.

To test this behavior, call the removeDocument method in the main function.

Creating secondary indexes

You can create a secondary index for any property of a document in a collection using the following code:

Just like before, update the main function to use the createIndex method.

Wrapping up

This is just an overview of some of the features and API methods for taping into the MySQL document store using the Node.js connector and the X Dev API. For additional details, check the following links:

MySQL Connector/Python 8.0.11 has been released

Dear MySQL users,

MySQL Connector/Python 8.0.11 is the first GA release version of the MySQL Connector Python 8.0 series. This series adds support for the new X DevAPI. The X DevAPI enables application developers to write code that combines the strengths of the relational and document models using a modern, NoSQL-like syntax that does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see http://dev.mysql.com/doc/x-devapi-userguide/en/. For more information about how the X DevAPI is implemented in MySQL Connector/Python, and its usage, see http://dev.mysql.com/doc/dev/connector-python.

Please note that the X DevAPI requires MySQL Server version 5.7.12 or higher with the X Plugin enabled. For general documentation about how to get started using MySQL as a document store, see http://dev.mysql.com/doc/refman/5.7/en/document-store.html.

To download MySQL Connector/Python 8.0.11, see the “General Available
(GA) releases” tab at http://dev.mysql.com/downloads/connector/python/

Enjoy!


Changes in MySQL Connector/Python 8.0.11 (2018-04-19)

     * Functionality Added or Changed

     * Bugs Fixed

   Functionality Added or Changed

     * X DevAPI: Previously, when documents without an _id
       attribute were added to a collection, Connector/Python
       automatically generated _id for them. Now a MySQL 8
       server generates the _id attribute unless a document
       already contains one. The generated IDs resulting from a
       document-add operation can be obtained using the new
       get_generated_ids() method.
       This capability requires a MySQL 8.0 server. Because
       MySQL 5.7 does not support document ID generation, the
       document-add operation returns an error if you do not
       define the _id's.
       Incompatibility: The get_generated_ids() method replaces
       the now removed get_document_ids(). (Bug #27627366)

     * Added NOWAIT and SKIP_LOCKED support to the
       ReadStatement.lock_shared() and
       ReadStatement.lock_exclusive() methods. Example usage:
       lock_exclusive(mysqlx.LockContention.SKIP_LOCKED).

     * The C extension (cext) is now enabled by default, as the
       use_pure option changed from True to False by default.
       If the C extension is not available on the system then
       the Python implementation is used instead, and use_pure
       is set to True.

     * Added the X DevAPI SHA256_MEMORY authentication
       mechanism.
       Example mysqlx.get_session() usages: ?auth=SHA256_MEMORY
       via a connection string, "auth":
       mysqlx.Auth.SHA256_MEMORY via a dictionary, or
       auth=mysqlx.Auth.SHA256_MEMORY via method parameters.

   Bugs Fixed

     * Warnings are now stored as a list of dictionaries instead
       of a list of tuples. In other words, get_warnings()
       returns the likes of [{"level": _level_, "code": _code_,
       "msg": _msg_}] instead of [(_level_, _code_, _msg_))].
       (Bug #27639119)

     * The mapped MySQL Server error codes were synced with
       MySQL Server 8.0.11. (Bug #27634885)

     * Removed upsert functionality from InsertStatement as it
       can only be used by collections, so upsert remains
       available to AddStatement. (Bug #27589450)

     * MySQLConverter.escape() functionality was added to
       create_schema()'s count mechanism. (Bug #27528842)

     * When using prepared statements, string columns were
       returned as bytearrays instead of strings. The returned
       value is now a string decoded using the connection's
       charset (defaults to 'utf8'), or as a bytearray if this
       conversion fails. (Bug #27364914)

     * The result from JSON_TYPE() was returned as a bytearray
       instead of a string. The returned value is now a string
       decoded using the connection's charset (defaults to
       'utf8'), or as a bytearray if this conversion fails. (Bug
       #24948205, Bug #83516)

     * JSON integer values were cast to bytes in Python instead
       of integers. (Bug #24948186, Bug #83513)

On Behalf of Oracle/MySQL Release Engineering Team
Prashant Tekriwal

MySQL 8.0 – Welcome to the DevAPI!

 

By now you’ve read Mike Frank’s excellent introduction to the MySQL 8.0 release and it’s Document Store.  In that post Mike laid out the benefits of the new Document Store model and briefly outlined the different components involved.  While it’s fair to consider the Document Store as the first pillar of the new MySQL 8 Document story, we must identify the X DevAPI to be the second.  The post covers our motivation, goals, and overall design principles of this new API.

Motivation

Most of our connectors have not implemented their own API.  Rather, most of them implement externally defined interfaces.   Examples include our Connector/J that implements the JDBC standard, Connector/Net that implements the ADO.Net standard, and our Connector/ODBC.  None of these standards work well for a document-oriented database.  In fact, there really are no defined standard APIs for document databases.  Therefore we knew we needed to develop a new API for our users.

Another reason why we needed a new API is because we are doing something that has not been done before.  Document databases exist.  Relational databases exist.  We even see databases that support relational and document querying over the same data set.  However we have yet to see a relational database include a document model so that a user can use document objects alongside their existing relational data.

We are only beginning to bring forth the unifying power of MySQL 8.   In the coming releases you’ll see exciting developments like being able to link your existing relational data with your document data in a single query using simple API patterns.

Goals

We have some very clear goals we follow as we develop the X DevAPI.  They are:

  • Simplicity — No one likes a complicated API.  We wanted the API to be easy to understand no matter what language you are using.   It’s important to us that if you write X DevAPI code using Node.JS then a Python developer, for example, can read it and know what is going on.
  • Bridge the gap between relational and document data — MySQL runs some of the world’s largest web properties and they have petabytes of relational data.  Asking them to add tables or columns to their data stores can be very challenging.  The new document store allows connecting these different types of data in the same queries.  We want to provide a powerful API for this.
  • Expressive — We wanted our API to be very expressive and follow a fluent interface style of development.  We wanted this to enable writing and executing the same X DevAPI code in the shell as in your application.
  • Seamless support for InnoDB Cluster farms — We want the API to seamlessly and transparently allow simple development of applications that span from one machine to hundreds.

Please note that these are goals. Some of them may not be fully realized in the initial release of the X DevAPI but these goals outline what we are thinking about during this development.

Design

No matter what connector you use the design of the X DevAPI core components remains the same.  The API involves some central objects outlined below. You’ll hear more about these objects and more in the individual product announcements and in our documentation found at https://dev.mysql.com/doc/.

Session Represents a logical connection to a server or farm
Schema Represents a MySQL database/schema
Collection Represents a collection of JSON documents
Result There’s a series of Result objects that handle different scenarios

Our goal is that each connector will include a core API (set of objects, properties and methods) that are the same across all connectors.  Outside of the core API, each connector can and will provide additional syntax or support additional methods.

Of course we also realize that each language and framework has it’s own style and it’s important to us to be respectful of that.  An example might be a count property that might appear as .Count  in one language but should be represented as .getCount()  in another.  Again, please recognize they are the same concept just different syntax.

Looking at the New X DevAPI Syntax

You’ll learn much more about the X DevAPI and our different languages when you read our announcement blogs and our documentation but I wanted to take just a minute to give quick examples of how you can use the X DevAPI in the shell to do quick ad-hoc prototyping.  First let’s look at opening a session to server.  In this example we open a session  to localhost and get a reference to the test schema so we can work with it.

Next we’ll create a collection and add a document to it.

We can modify the document very easily.  This example finds all documents that have a length of 250 and changes that length to 125.

We can find those documents if we want to work with them

And finally we can remove the documents and drop our collection

These have just been some quick examples but we hope that it has shown some of the basic ideas we have in the X DevAPI and you are interested in learning more and trying it out.

Availability

With the release of MySQL 8.0 we are also making available 8.0 GA versions of our connectors.  Each of them, save ODBC, provide an initial implementation of X DevAPI.  These connectors should be installed from their respective package stores.  You can also find them at our website at https://www.mysql.com/downloads/.

You can read much more about each of the products on their announcement blogs:

We know that we have not covered every language available.  If you are using MySQL 8 with a connector in a different language please let us know.  We want to work with the community to bring X DevAPI to more and more languages.

Thank you!

I want to thank you for your time to read this and learn about our new products.  I hope that you will take the time to get to know what we’ve created and let us know where we fell down.  We have much more planned and we want to hear from you!

Introducing Connector/Node.js for MySQL 8.0

As you may have heard, MySQL 8.0 is now officially GA, and it comes with a bunch of additional goodies. Among those is the brand new Connector/Node.js, which is the official MySQL driver for Node.js and, currently, the only one with support for the latest server versions and features (such as the MySQL document store).

Here’s a rundown of what’s available:

  • Out-of-the box support for MySQL 8.0
  • Document-store API as a first-class citizen
  • TLS/SSL and SHA256 authentication
  • Fluent API with support for flexible parameters
  • Semantic methods to encode common CRUD operations
  • Modern Node.js asynchronous interface based on Promises
  • Abstractions for common database development tasks
  • Transactions, savepoints and row locking

MySQL 8.0

Connector/Node.js is currently the only driver in the Node.js ecosystem that works out-of-the-box with the latest MySQL 8.0 series and implements the brand new X Protocol and X DevAPI, which unlocks exclusive server features such as the MySQL document store.

In a nutshell, the X Protocol is based on the Google Protocol Buffers serialization format, and provides a common interface for a different set of official connectors to bridge into the MySQL server via the X plugin, which contains the server-side implementation of the document store and a surrounding scaffolding ecosystem including things like common CRUD expression trees, bound parameters, or expectations and conditions for statement pipelining.

The X DevAPI is the common client-side API used by all connectors to abstract the details of the X Protocol. It specifies the common set of CRUD-style functions/methods used by all the official connectors to work with both document store collections and relational tables, a common expression language to establish query properties such as criteria, projections, aliases, and a standard set of additional database management features for handling things like transactions, indexes, etc.

The fact that most of these features share the same format and API between connectors, makes the X DevAPI a perfect fit for mordern polyglot development environments such as microservices, and the fact that they are based on a well-documented format allows advanced users to extend client-side implementations and build new middleware components or extensions tailor-made for their use case.

Although, there are (most of the times) matching client APIs to work with relational tables, this overview will focus mostly on document-store related features. Check the official Connector/Node.js documentation or the X DevAPI user guide to get the full picture.

Secure by default

With Connector/Node.js, SSL/TLS is enabled by default for server TCP connections and, additionally, the server identity can be validated against a given certificate authority (CA).

Of course you can explicitely override this behavior (at your own peril).

Local Unix sockets don’t use SSL/TLS since they don’t really benefit much from that level of security. At the same time, that removes the possibility of any additional performance overhead caused by the SSL/TLS handshake.

In the authentication realm, besides the traditional SHA1-based server authentication plugin, Connector/Node.js also supports the latest secure authentication plugins based on SHA-256. Of course you can always use your own custom server plugins, as long as the authentication data can be sent using one of the existing client-side authentication mechanisms (in the simplest form, via plain text).

Additional details about Connector/Node.js security can be found here.

Fluent API

The public API flows nicely from a single getSession()  method. Whereas, when it comes the point of creating and issuing database operations, you get a nice fluent query builder where those operations are encapsulated in specialized and specific methods, which, compared to using raw SQL statements, brings benefits such as:

  • more readable, maintainable (and even testable) code
  • better tooling integration
    • scaffolding for code refactoring
    • text-editor (or IDE) hints and auto-completion
  • smaller SQL injection surface area
  • common standard between different programming languages and environments

Most public API methods provide alternative input handling flavors:

  • multiple individual arguments
  • a single array of arguments
  • an object with named properties (where it applies)

Promise-based asynchronous tasks

Being a good Node.js citizen, Connector/Node.js encapsulates all blocking I/O operations with asynchronous methods. Each method that sends a message to the MySQL server is expected to return a JavaScript Promise , which resolves to the specific result or fails with an error. This pattern also unlocks other platform abstractions such as the async/await  syntax, making it even more flexible for the user than just using traditional error-first callbacks.

So, after building a query, it can be sent to the server via the execute()  method. In turn, the method receives an optional callback as argument, which runs for each element in the result set. When using relational tables, an additional callback function can be used to tap into the given column metadata.

Other methods, such as the ones that operate on a single instance of a connection, database object (be it a schema, table/collection, row, document, etc.) will return a Promise  by themselves (dropping the extra call to execute() ). Some examples:

  • mysqlx.getSession()
  • session.getSchemas()
  • session.createSchema()
  • schema.getCollections()
  • schema.createCollection()
  • collection.getOne()
  • collection.addOrReplaceOne()
  • collection.replaceOne()
  • collection.createIndex()

Data consistency

With MySQL 8.0, you get session-level consistency and document-level isolation via multiple database constructs, such as transactions, savepoints and row locking. This allows to encapsulate a set of operations (particularly DML) encompassing multiple documents or collections in a single atomic procedure within a given session.

Connector/Node.js provides APIs to create, commit or rollback a transaction as well as to create, release or rollback to an intermediate savepoint within that transaction.

In the presence of concurrent transactions, the isolation level of each operation within the transaction, operating on a given document, can be determined using row locks.

Raw SQL interface

If you are looking for a feature that is still not available on the X DevAPI, or simply something that does not fit the CRUD model, you can always resort to plain old SQL.

Getting Started

If you want to use Connector/Node.js in your own project or just want to play around with, download the latest version from npm:

New releases DO NOT follow semantic versioning, so, to avoid being affected by breaking changes, make sure you use --save-exact  when pulling the package, particularly if you don’t have npm-shrinkwrap.json  or package-lock.json  files locking down your project’s dependencies.

If you are an advanced user, being an open source project, the code is hosted on the official GitHub repository and contributions are welcome, either in the form of bugs ( Connector for Node.js  category) or pull requests.

Up and Running

Assuming you are running MySQL 8.0 with the default configuration and Node.js v8.0.0  or later (for async/await  support), using Connector/Node.js and the MySQL document store in your project is as simple as follows:

These are just some of the highlights. Make sure you check out the official Connector/Node.js documentation or the X DevAPI user guide for usage examples and even more details on how to get started.

Please give it a try! Your feedback is more than welcome.

Using MySQL Connector/Python 8.0 with MySQL 8.0

The MySQL Connector/Python Team is pleased to announce MySQL Connector/Python 8.0.11, the first GA 8.0 release series of the official MySQL driver for Python. This release introduces the first Python driver that adds full MySQL 8.0 support.

Document Store

MySQL 8.0 includes many improvements and new features, with Document Store being the biggest.

MySQL Document Store is schema-less with a flexible data structure storage system for documents. This removes the requirement for schema design, normalization, foreign keys, constrains, and data types.

The Document Store is accessible by the X DevAPI, an API that introduces a new modern and easy-to-learn way to work with your data that is implemented by all MySQL Connectors that support the X Protocol, such as MySQL Connector/Python.

Getting Started

Installation

Requirements:

The recommended way to install Connector/Python is via pip.

Packages are also available from the MySQL Connector/Python downloads site. For some packaging formats, there are different packages for different versions of Python. Choose the one appropriate for the version of Python installed on your system.

For installation documentation, please visit the Connector/Python installation guide.

Writing your first program using the MySQL Document Store

Assuming Connector/Python 8.0 is installed on your system and you’re accessing a MySQL 8.0 server, you’re ready to write your first program using the MySQL Document Store.

For a detailed explanation of this code, please visit the Getting Started section of the official MySQL Connector/Python X DevAPI Reference Documentation.

Improved Security

Server TCP connections are now secure by default, meaning the default SSL Mode is now set to REQUIRED (mysqlx.SSLMode.REQUIRED).
Support was also added for the latest secure MySQL 8 authentication plugins based on SHA-256 hashing, such as new the caching_sha2_password authentication plugin. Usage can be implicit or explicit, for example:

Fluent API

The X DevAPI operations are structured to be “fluent”. This means it’s possible to call multiple methods to modify an object prior to execution, which enables a fluent query builder and allows more readable, maintainable, and secure code.

An example is following where where() and sort() are fluent methods to modify the find operation prior to executing it.

Support for raw SQL statements

The X DevAPI allows you to execute raw SQL statements to combine the flexibility of the document store model with the power of the relational model.

Transactions, Savepoints and Row Locking

Connector/Python provides an API to create, commit, or rollback a transaction, and also to create, release, or rollback to an intermediate savepoint within that transaction.

An optional savepoint name can be defined to create a transaction savepoint, which can later be used to rollback.

If a savepoint name is not provided, then mysqlx.Session.release_savepoint() will return a generated savepoint name.

To learn more about writing applications using the MySQL X DevAPI with Connector/Python and other MySQL connectors and clients, see http://dev.mysql.com/doc/x-devapi-userguide/en/

For general documentation about how to get started using MySQL as a document store, see https://dev.mysql.com/doc/refman/8.0/en/document-store.html

For more information about how the X DevAPI is implemented in MySQL Connector/Python, and its usage, see https://dev.mysql.com/doc/dev/connector-python/8.0/

We welcome and appreciate your feedback and bug reports: http://bugs.mysql.com/

Enjoy!

Introducing the MySQL X DevAPI PHP Extension for MySQL 8.0

MySQL 8.0 is now finally GA, bringing into play the powerful Document Store set of feature along with Connectors for many of the most popular languages! Also PHP is coming with it’s own extension designed to support all of the new exciting feature coming with this latest MySQL milestone.

The complete web documentation for the MySQL X DevAPI Extension for PHP is available here.

About Document Store.

The X DevAPI for PHP is an extension which allows the user to access MySQL with installed the X Plugin as a document store via the X DevAPI and the related underlying protocol.

A document store differs substantially from a traditional relational database organization where a schema needs to be provided in order to push data into the database, a document store permit to insert information in a non-uniform manner, thus without the requirement of defining and maintaining a specific set of schema’s –and their links– needed to properly store the object being recorded.

This database model became very popular with NoSQL and other similar products, the MySQL document store X Plugin has the purpose of allowing the MySQL users to retain their current  MySQL configurations and being able to benefit from the new schema-less data organization.

Different language connectors are provided to access MySQL as Document Store, and in this post I’m going to focus on the powerful and widely used PHP language and it’s xdevapi extension which is the key use this MySQL functionality.

What does that mean in short? It means that now you can store non homogeneous data in your database without the need to define and specify meticulously the content of the tables, just open a xdevapi session and push your data into the database!

Installing the PHP extension

The easier way to install the extension is by using pecl tool or is possible to download the tarball file directly from this link. There are some dependencies to fulfill in order to use the extension, the most relevant is certainly boost and the protobufs libraries.

PHP Extension for MySQL 8.0 and Document Store.

First of all we need to create a connection to the database, in order to do so you need to access the mysql_xdevapi namespace and call the getSession function. getSession accepts as parameter the URI string with the credentials and address of the target server, in my example the URI is going to be: “mysqlx://root:XXX@localhost:33060/?ssl-mode=disabled“, probably during your configuration of MySQL you’ve chosen a different password so please use yours instead of XXX!

The URI strings starts with the required “mysqlx” followed by your credentials and the address of the server, the port 33060 is the default one where MySQL is listening for X DevAPI connections. Also, by default the connection with the server is going to be over SSL, is possible to change this default behavior by providing the proper ssl-mode, like in the example below:

$nodeSession is the object which handle the session for the current connection. Let’s see how to create a schema, a collection for documents and how to add a simple document:

In this code example the first two lines are for the purpose of creating a schema and a collection within the schema, in all the following samples I’ll use the variable $coll as a reference to the Collection obtained by createCollection

With the add you can trigger the insertion of a new document into the collection, each add has to be followed by the execute command, in the example code I’m submitting two documents with one add operation, you can add as many documents as you want with a single operation, each document have to be separated by a comma.

The same execute command is required by most of the DevAPI functions, before the execution of the request additional operations could be performed like adding more documents, manipulating the fields &c. The documents I’m inserting in the code sample are easy to understand JSON, if you are not familiar with JSON please have a look here.

We can verify the content of the database as well:

So, from this last shell output is clear what a collection is and how a document looks like! A collection is just a table with two columns, one representing the document itself which is a JSON and the other is the unique identifier of the document –which is a varchar-! Those ID’s are generate automatically for each inserted document, you can provide your own ID’s if you want.

The $result object returned by the add operation can be used to verify what changes has been applied to the collection or to obtain a list of the ID’s generated by the server while adding the documents.

Manipulating the documents

Let’s see how easily those Collections can be manipulated, for example removing documents can be done by using the straightforward removeOne API, which is a function that expect one single argument, the ID of the document to remove:

Is possible to look for documents using the find operation, in it’s most basic implementation the find function will require an expression that can be used to match the document to extract from the collection:

As last example here’s how is possible to modify the content of a document using the powerful modify operation. The only argument to modify is an expression that can be used to identify the documents that have to be modified, it’s then followed by one or more operation that define the modification:

Conclusion

There’s a strong feeling of excitement around MySQL 8.0 and his features, in particular Document Store is going to be a game changes in the industry by providing a powerful and flexible tool into the most popular and recognized DB.

MySQL Connector/NET 8.0.11 has been released

Dear MySQL users,

MySQL Connector/NET 8.0.11 is the first general availability release of
Connector/NET to add support for the new X DevAPI. The X DevAPI
enables application developers to write code that combines the strengths
of the relational and document models using a modern, NoSQL-like syntax
that does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see
http://dev.mysql.com/doc/x-devapi-userguide/en/index.html. For more
information about how the X DevAPI is implemented in Connector/NET, see
http://dev.mysql.com/doc/dev/connector-net. Users relying on NuGet                packages need to install the MySql.Data package to be able to use the                          X DevAPI.

Please note that the X DevAPI requires at least MySQL Server version
5.7.12 or higher with the X Plugin enabled. For general documentation
about how to get started using MySQL as a document store, see
http://dev.mysql.com/doc/refman/5.7/en/document-store.html.

To download Connector/NET 8.0.11, see
http://dev.mysql.com/downloads/connector/net/.

Installation instructions can be found at https://dev.mysql.com/doc/connector-net/en/connector-net-installation.html.


Changes in MySQL Connector/NET 8.0.11 (2018-04-19)

   Functionality Added or Changed

     * X DevAPI: Connector/NET now supports the NOWAIT and
       SKIP_LOCKED locking options introduced in the MySQL 8.0
       release series (see SELECT Syntax
       (http://dev.mysql.com/doc/refman/5.7/en/select.html)).
       The following changes were made to the Connector/NET API:

          + The LockContention enumeration (with values
            Default=0, NoWait=1 and SkipLocked=2) was added. The
            Default enumeration member represents the previous
            behavior of waiting for the row locks to be
            released.

          + The existing LockShared() and LockExclusive() method
            signatures were modified to include the new
            LockContention parameter. Both methods are members
            of the MySqlX.XdevAPI.CRUD.FindStatement and
            MySqlX.XdevAPI.Relational.TableSelectStatement
            classes.

          + Usage examples:
// Default behavior - waits for the row locks to release
LockShared()
LockShared(LockContention.Default)

LockExclusive()
LockExclusive(LockContention.Default)

// New - fails if the rows are locked
LockShared(LockContention.NoWait)
LockExclusive(LockContention.NoWait)

// New - succeeds excluding the locked rows from the result
LockShared(LockContention.SkipLocked)
LockExclusive(LockContention.SkipLocked)


     * X DevAPI: Previously, when documents without an _id
       attribute were added to a collection, Connector/NET
       automatically generated IDs for them. Now the server
       generates the _id attribute, unless a document already
       contains one. The generated IDs resulting from a
       document-add operation can be obtained using the new
       Result.GeneratedIds property, which returns a list.
       This capability requires a MySQL 8.0 GA server. If the
       server does not support document ID generation, the
       document-add operation returns an error indicating that
       document IDs were missing.
       Incompatibility: The GeneratedIds property replaces the
       DocumentId and DocumentIds properties, which are now
       removed.

     * X DevAPI: Support for the SHA256_MEMORY authentication
       mechanism was added to enable non-PLAIN insecure
       connections (without SSL) for user accounts with
       caching_sha2_password, which is the default
       authentication plugin introduced in the MySQL 8.0 release
       series. The changes related to this support include:

          + New synonyms for the auth connection string option:
            authentication and authentication mode (see General
            Options
           (http://dev.mysql.com/doc/connector-net/en/connector-net-connection-options.
          html#connector-net-connection-options-general)).

          + A new authentication mode for the
            MySqlAuthenticationMode enumeration: SHA256_MEMORY.
            In addition, the Default member now has a new
            synonym: Auto=0.

          + A new class:
            MySql.Data.MySqlClient.Authentication.Sha256MemoryAu
            thenticationPlugin.

     * Support was added for the new caching_sha2_password
       padding mechanism introduced in the MySQL 8.0 release
       series. The new padding mechanism is enabled when all of
       the following conditions apply:

          + The user account is set with the
            caching_sha2_password authentication plugin.

          + SSL is disabled explicitly (SslMode=none).

          + The AllowPublicKeyRetrieval connection option is
            enabled (AllowPublicKeyRetrieval=true).
       When enabled, the new padding mechanism is used to encode
       the password during RSA key encryption, which applies the
       correct padding to match the server.

   Bugs Fixed

     * Attempting to open the MySQL Web Configuration Tool, with
       Connector/NET and MySQL for Visual Studio prerequisites
       installed properly, displayed an error message instead of
       opening the tool. (Bug #27457398, Bug #88544)

     * MySQL Installer could not be installed with NuGet
       packages from Microsoft Visual Studio 2015. (Bug
       #27251839, Bug #88838)

     * When a decimal column was defined with a scale of zero,
       such as DECIMAL(8, 0), the value of the NumericPrecision
       field returned by the MySqlDataReader.GetSchemaTable
       method was lower by one. For example, it returned 7
       instead of 8 as expected. (Bug #26954812, Bug #88058)

     * The data table returned by the
       MySqlDataReader.GetSchemaTable method had an inaccurate
       value of zero assigned to the ColumnSize field for
       LONGTEXT and LONGBLOB data types, and also indicated that
       the IsLong field value was false when it should have
       returned true. (Bug #26876592, Bug #87876)

     * The MySqlDataReader.GetSchemaTable method returned
       different column-size values when used with different
       character sets. (Bug #26876582, Bug #87868)

     * Support for making a secure connection to a server
       configured to use TLSv1.2 was limited by external
       factors. (Bug #25689154)

     * Connection strings that included TLS/SSL connection
       parameters in URI type-string format generated an
       exception instead of making a connection with the X
       Protocol. (Bug #24510329)

     * Attempting to generate an Entity Framework model from a
       MySQL 5.7 database using either EF5 or EF6 produced an
       exception that prevented the operation from generating
       the expected model. (Bug #22173048, Bug #79163)

What is new in Connector/ODBC 8.0

General information about MySQL Connector/ODBC 8.0:

MySQL Connector/ODBC 8.0 is a successor of the Connector/ODBC 5.3 line.
The Connector/ODBC driver 8.0 becomes available starting from the version 8.0.11.

Where is 8.0.10? The family of MySQL products is growing and with so many products and different versions it is easy to get confused about functionality and product compatibility. Therefore, we decided to unify the versioning and synchronize the version numbers across all MySQL products. The current GA version of MySQL Server is 8.0.11 and the family of MySQL Connectors including Connector/ODBC has been aligned with the new versioning model and became 8.0.11 too. This will ensure that Connector/ODBC 8.0.11 can work with MySQL Server 8.0.11.

Among bug fixes and internal improvements the Connector/ODBC 8.0.11 received the support for a new authentication methods introduced in MySQL Server 8.0. These new authentication methods require encrypted connection in case password needs to be sent to the server (cache miss). If, for some reason, SSL connection is not an option, passwords still can be sent to the server after encrypting it with server’s public key. A new connection option GET_SERVER_PUBLIC_KEY requests server to send its public key when it is needed. This way clients can connect even if they do not know server’s public key. However, using this option is prone to man-in-the-middle attacks, so it should be used only in situations where you can ensure by other means that your connections are made to trusted servers.

The value of GET_SERVER_PUBLIC_KEY is a boolean, and added in 8.0.11.By default the option is not enabled, but setting it is really easy and can be done in two ways:

  • Through the GUI DSN Setup dialog. Click “Details >>” and tick [x] Get Server Public Key as shown here:

    ODBC GUI Dialog with GET_SERVER_PUBLIC_KEY

    ODBC GUI Dialog with GET_SERVER_PUBLIC_KEY option

  • By specifying the option in the connection string:
    “…GET_SERVER_PUBLIC_KEY=1…”

This capability requires a MySQL 8 server, and is supported only for Connector/ODBC built using OpenSSL. This option is ignored when used with MySQL Server 5.7.

NOTE: There is a way to specify RSA Public key if it is located on the client host. In GUI DSN Setup dialog. Click “Details >>”, select the “SSL” tab and specify the location of RSA Public Key as shown here:

ODBC GUI Dialog with RSAKEY option

ODBC GUI Dialog with RSAKEY option

Alternatively, the RSA Public Key can be given through the connection string as
“…RSAKEY=D:\\ssl\\mykey.pub;…”. The double back-slashes are there because in languages like C or C++ they must be properly escaped.

There are a few things to keep in mind when using MySQL Connector/ODBC 8.0:

  • For maximum security the connection to MySQL Server is established using SSL/TLS by default. All communication between ODBC Driver and MySQL Server would be encrypted using a separate OpenSSL library. For previous versions of MySQL ODBC Driver such as 5.7 the SSL code would be embedded into the driver library file. This is changed in Connector/ODBC 8.0 where OpenSSL shared library is required for the driver to work. The reason for doing it is improving of the security: when the new security update for OpenSSL is released the user can update OpenSSL right away without waiting on the new version of Connector/ODBC driver (which would be necessary if SSL library is embedded). However, in order to work the ODBC driver needs to be able to find and load OpenSSL shared library even if SSL/TLS connection is not used. Most packages released for the version 8.0.11 bundle the latest OpenSSL library files (libeay32.dll/ssleay32.dll for Windows platforms and libcrypto.so/libssl.so for Linux/Unix platforms). Such packages are ready for work out-of-box (assuming that UnixODBC (Linux/Unix) or iODBC (OSX) is installed). Packages for the enterprise platforms such as Red Hat Enterprise Linux or Suse Linux Enterprise Server do not have bundled OpenSSL libraries because in most cases OpenSSL is already installed on these platforms. Also, in enterprise platforms the administrators often update OpenSSL as soon as a new security patch is available.
  • The Windows platform will no longer receive 32-bit builds of MySQL Connector/ODBC 8.0 (Note: there is no 32-bit MySQL Server 8.0 as well).
  • The ODBC Driver 8.0 for Windows needs the Visual C++ 2015 runtime libraries for its work. These libraries are included in Visual C++ 2015 64-bit redistributable package, which can be downloaded from the Microsoft web site.NOTE: VC++ 2017 redistributable package is not a replacement for VC++ 2015. Therefore, even if VC++ 2017 is installed in the system, the 2015 version is still required.

Typical errors that can happen during the installation or setup:

Trying to run an ODBC Driver 8.0 MSI installation package without VC++ 2015 redistributable libraries will result in to following error message dialog:

VC++ 2015 redistributable not found

VC++ 2015 redistributable not found

The solution is to install the 2015 redistributable package and run MSI installer again.

Sometimes the driver is installed without MSI package manually. An attempt to load a Setup module (myodbc8S.dll) from ODBC Administrator without VC++ 2015 redistributable will result in the following error:

Failure to load myodbc8a.dll

Failure to load myodbc8a.dll

Unfortunately, the Windows ODBC Administrator does not give detailed information about the problem why the setup routine could not be loaded. If you see an error dialog like that it is most likely because the VC++ 2015 redistributable package is not installed.