Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 35.1Mb
PDF (A4) - 35.2Mb
Man Pages (TGZ) - 256.4Kb
Man Pages (Zip) - 361.2Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  / Using MySQL as a Document Store  /  Setting Up MySQL as a Document Store

19.2 Setting Up MySQL as a Document Store

To use MySQL 5.7 as a document store, the X Plugin needs to be installed. Then you can use X Protocol to communicate with the server. Without the X Plugin running, X Protocol clients cannot connect to the server. The X Plugin is supplied with MySQL (5.7.12 or higher) — installing it does not involve a separate download. This section describes how to install X Plugin.

Follow the steps outlined here:

  1. Install or upgrade to MySQL 5.7.12 or higher.

    When theinstallation or upgrade is done, start the server. For server startup instructions, seeSection 2.9.2, “Starting the Server”.

    Note

    MySQL Installer enables you to perform this and the next step (Install the X Plugin) at the same time for new installations on Microsoft Windows. In thePlugin and Extensions screen, check mark theEnable X Protocol/MySQL as a Document Store check box. After the installation, verify that the X Plugin has been installed.

  2. Install the X Plugin. A non-root account can be used to install the plugin as long as the account hasINSERT privilege for themysql.plugin table.

    Always save your existing configuration settings before reconfiguring the server.

    To install the built-in X Plugin, do one of the following:

    • UsingMySQL Installer for Windows:

      1. Launch MySQL Installer for Windows. MySQL Installer dashboard opens.

      2. Click theReconfigure quick action for MySQL Server. UseNext andBack to configure the following items:

        • InAccounts and Roles, confirm the currentroot account password.

        • InPlugin and Extensions, check mark theEnable X Protocol/MySQL as a Document Store check box. MySQL Installer provides a default port number and opens the firewall port for network access.

        • InApply Server Configuration, clickExecute.

        • ClickFinish to close MySQL Installer.

      3. Install MySQL Shell.

    • Using MySQL Shell:

      1. Install MySQL Shell.

      2. Open a terminal window (command prompt on Windows) and navigate to the MySQL binaries location (for example,/usr/bin/ on Linux).

      3. Run the following command:

        mysqlsh -uuser -h localhost --classic --dba enableXProtocol

    • Using the MySQL Client program:

      1. Open a terminal window (command prompt on Windows) and navigate to the MySQL binaries location (for example,/usr/bin/ on Linux).

      2. Invoke themysql command-line client:

        mysql -uuser -p

      3. Issue the following statement:

        mysql> INSTALL PLUGIN mysqlx SONAME 'mysqlx.so';

        Replacemysqlx.so withmysqlx.dll for Windows.

        Important

        Themysql.session user must exist before you can load X Plugin.mysql.session was added in MySQL version 5.7.19. If your data dictionary was initialized using an earlier version you must run themysql_upgrade procedure. If the upgrade is not run, X Plugin fails to start with the error messageThere was an error when trying to access the server with user: mysql.session@localhost. Make sure the user is present in the server and that mysql_upgrade was ran after a server update..

      4. Install MySQL Shell.

  3. Verify that the X Plugin has been installed.

    When the X Plugin is installed properly, it shows up in the list when you query for active plugins on the server with one of the following commands:

    • MySQL Shell command:

      mysqlsh -uuser --sqlc -e "show plugins"

    • MySQL Client program command:

      mysql -uuser -p -e "show plugins"

    If you encounter problems with the X Plugin installation, or if you want to learn about alternative ways of installing, configuring, or uninstalling server plugins, seeSection 5.5.1, “Installing and Uninstalling Plugins”.

mysqlxsys@localhost User Account

Installing the X Plugin creates amysqlxsys@localhost user account. If, for some reason, creating the user account fails, the X Plugin installation fails, too. Here is an explanation on what themysqlxsys@localhost user account is for and what to do when its creation fails.

The X Plugin installation process uses the MySQLroot user to create an internal account for themysqlxsys@localhost user. Themysqlxsys@localhost account is used by the X Plugin for authentication of external users against the MySQL account system and for killing sessions when requested by a privileged user. Themysqlxsys@localhost account is created as locked, so it cannot be used to log in by external users. If for some reason the MySQLroot account is not available, before you start the X Plugin installation you must manually create themysqlxsys@localhost user by issuing the following statements in themysql command-line client:

CREATE USER IF NOT EXISTS mysqlxsys@localhost IDENTIFIED WITHmysql_native_password AS 'password' ACCOUNT LOCK;GRANT SELECT ON mysql.user TO mysqlxsys@localhost;GRANT SUPER ON *.* TO mysqlxsys@localhost;

Uninstalling the X Plugin

If you ever want to uninstall (deactivate) the X Plugin, issue the following statement in themysql command-line client:

UNINSTALL PLUGIN mysqlx;

Do not use MySQL Shell to issue the previous statement. It works from MySQL Shell, but you get an error (code 1130). Also, uninstalling the plugin removes the mysqlxsys user.